release: cut the v8.1.3 release

No longer locks the Material unit tests job to a specific branch, but rather allows
locking to a specific commit from a given branch. This allows us to use the
"master" branch from the `components` repository.

PR Close #31569

PR Close #31847

.bazelignore

@@ -1,3 +1,4 @@
+.git
 node_modules
 dist
 aio/content

.bazelrc

@@ -1,14 +1,3 @@
-###############################
-# Typescript / Angular / Sass #
-###############################
-
-# Make compilation fast, by keeping a few copies of the compilers
-# running as daemons, and cache SourceFile AST's to reduce parse time.
-build --strategy=AngularTemplateCompile=worker
-# TODO(alexeagle): re-enable after fixing worker instability with rxjs typings
-# build --strategy=TypeScriptCompile=worker
-build --strategy=TypeScriptCompile=standalone
-
 # Enable debugging tests with --config=debug
 test:debug --test_arg=--node_options=--inspect-brk --test_output=streamed --test_strategy=exclusive --test_timeout=9999 --nocache_test_results
 
@@ -85,12 +74,6 @@ query --output=label_kind
 # By default, failing tests don't print any output, it goes to the log file
 test --test_output=errors
 
-# Show which actions are run under workers,
-# and print all the actions running in parallel.
-# Helps to demonstrate that bazel uses all the cores on the machine.
-build --experimental_ui
-test --experimental_ui
-
 ################################
 # Settings for CircleCI        #
 ################################
@@ -154,6 +137,31 @@ build:remote --bes_results_url="https://source.cloud.google.com/results/invocati
 # This allows us to avoid installing a second copy of node_modules
 common --experimental_allow_incremental_repository_updates
 
+# This option is changed to true in Bazel 0.27 and exposes a possible
+# regression in Bazel 0.27.0.
+# Error observed is in npm_package target `//packages/common/locales:package`:
+# ```
+# ERROR: /home/circleci/ng/packages/common/locales/BUILD.bazel:13:1: Assembling
+# npm package packages/common/locales/package failed: No usable spawn strategy found
+# for spawn with mnemonic SkylarkAction.  Your --spawn_strategyor --strategy flags
+# are probably too strict. Visit https://github.com/bazelbuild/bazel/issues/7480 for
+# migration advises
+# ```
+# Suspect is https://github.com/bazelbuild/rules_nodejs/blob/master/internal/npm_package/npm_package.bzl#L75-L82:
+# ```
+# execution_requirements = {
+#     # Never schedule this action remotely because it's not computationally expensive.
+#     # It just copies files into a directory; it's not worth copying inputs and outputs to a remote worker.
+#     # Also don't run it in a sandbox, because it resolves an absolute path to the bazel-out directory
+#     # allowing the .pack and .publish runnables to work with no symlink_prefix
+#     # See https://github.com/bazelbuild/rules_nodejs/issues/187
+#     "local": "1",
+# },
+# ```
+build --incompatible_list_based_execution_strategy_selection=false
+test --incompatible_list_based_execution_strategy_selection=false
+run --incompatible_list_based_execution_strategy_selection=false
+
 ####################################################
 # User bazel configuration
 # NOTE: This needs to be the *last* entry in the config.

.circleci/bazel.rc

@@ -28,3 +28,14 @@ test --flaky_test_attempts=2
 
 # More details on failures
 build --verbose_failures=true
+
+# We have seen some flakiness in using TS workers on CircleCI
+# https://angular-team.slack.com/archives/C07DT5M6V/p1562693245183400
+# > failures like `ERROR: /home/circleci/ng/packages/core/test/BUILD.bazel:5:1:
+# > Compiling TypeScript (devmode) //packages/core/test:test_lib failed: Worker process did not return a WorkResponse:`
+# > I saw that issue a couple times today.
+# > Example job: https://circleci.com/gh/angular/angular/385517
+# We expect that TypeScript compilations will parallelize wider than the number of local cores anyway
+# so we should saturate remote workers with TS compilations
+build --strategy=TypeScriptCompile=standalone
+build --strategy=AngularTemplateCompile=standalone

.circleci/config.yml

@@ -58,17 +58,7 @@ var_5: &setup_bazel_remote_execution
       # cause decryption failures based on the openssl version. https://stackoverflow.com/a/39641378/4317734
       openssl aes-256-cbc -d -in .circleci/gcp_token -md md5 -k "$CI_REPO_NAME" -out /home/circleci/.gcp_credentials
       echo "export GOOGLE_APPLICATION_CREDENTIALS=/home/circleci/.gcp_credentials" >> $BASH_ENV
-      touch .bazelrc.user
-      sudo bash -c "echo -e 'build --config=remote\n' >> .bazelrc.user"
-      sudo bash -c "echo -e 'build:remote --remote_accept_cached=true\n' >> .bazelrc.user"
-      echo "Reading from remote cache for bazel remote jobs."
-      if [[ "$CI_PULL_REQUEST" == "false" ]]; then
-        sudo bash -c "echo -e 'build:remote --remote_upload_local_results=true\n' >> .bazelrc.user"
-        echo "Uploading local build results to remote cache."
-      else
-        sudo bash -c "echo -e 'build:remote --remote_upload_local_results=false\n' >> .bazelrc.user"
-        echo "Not uploading local build results to remote cache."
-      fi
+      ./.circleci/setup-rbe.sh .bazelrc.user
 
 # Settings common to each job
 var_6: &job_defaults
@@ -138,7 +128,7 @@ var_13: &notify_caretaker_on_fail
     # `$SLACK_CARETAKER_WEBHOOK_URL` is a secret env var defined in CircleCI project settings.
     # The URL comes from https://angular-team.slack.com/apps/A0F7VRE7N-circleci.
     command: |
-      notificationJson="{\"text\":\":x: \`$CIRCLE_JOB\` job failed on build $CIRCLE_BUILD_NUM: $CIRCLE_BUILD_URL :scream:\"}"
+      notificationJson="{\"text\":\":x: \`$CIRCLE_JOB\` job for $CIRCLE_BRANCH branch failed on build $CIRCLE_BUILD_NUM: $CIRCLE_BUILD_URL :scream:\"}"
       curl --request POST --header "Content-Type: application/json" --data "$notificationJson" $SLACK_CARETAKER_WEBHOOK_URL
 
 var_14: &notify_dev_infra_on_fail
@@ -148,9 +138,14 @@ var_14: &notify_dev_infra_on_fail
     # `$SLACK_DEV_INFRA_CI_FAILURES_WEBHOOK_URL` is a secret env var defined in CircleCI project settings.
     # The URL comes from https://angular-team.slack.com/apps/A0F7VRE7N-circleci.
     command: |
-      notificationJson="{\"text\":\":x: \`$CIRCLE_JOB\` job failed on build $CIRCLE_BUILD_NUM: $CIRCLE_BUILD_URL :scream:\"}"
+      notificationJson="{\"text\":\":x: \`$CIRCLE_JOB\` job for $CIRCLE_BRANCH branch failed on build $CIRCLE_BUILD_NUM: $CIRCLE_BUILD_URL :scream:\"}"
       curl --request POST --header "Content-Type: application/json" --data "$notificationJson" $SLACK_DEV_INFRA_CI_FAILURES_WEBHOOK_URL
 
+# Cache key for the Material unit tests job. **Note** when updating the SHA in the cache keys,
+# also update the SHA for the "MATERIAL_REPO_COMMIT" environment variable.
+var_15: &material_unit_tests_cache_key v4-angular-material-701302dc482d7e4b77990b24e3b5ab330bbf1aa5
+var_16: &material_unit_tests_cache_key_short v4-angular-material
+
 version: 2
 jobs:
   setup:
@@ -245,6 +240,11 @@ jobs:
           path: dist/bin/packages/core/test/bundling/todo/bundle.min.js.br
           destination: core/todo/bundle.br
 
+  # This job is currently a PoC for running tests on SauceLabs via bazel. It runs a subset of the
+  # tests in `legacy-unit-tests-saucelabs` (see
+  # [BUILD.bazel](https://github.com/angular/angular/blob/ef44f51d5/BUILD.bazel#L66-L92)).
+  #
+  # NOTE: This is currently limited to master builds only. See the `default_workflow` configuration.
   test_saucelabs_bazel:
     <<: *job_defaults
     # In order to avoid the bottleneck of having a slow host machine, we acquire a better
@@ -293,6 +293,8 @@ jobs:
       - run: yarn --cwd aio e2e --configuration=ci
         # Run PWA-score tests
       - run: yarn --cwd aio test-pwa-score-localhost $CI_AIO_MIN_PWA_SCORE
+        # Run accessibility tests
+      - run: yarn --cwd aio test-a11y-score-localhost
         # Check the bundle sizes.
       - run: yarn --cwd aio payload-size
         # Run unit tests for Firebase redirects
@@ -618,40 +620,36 @@ jobs:
     resource_class: xlarge
     docker:
       - image: *browsers_docker_image
-    # The Material unit tests support splitting the browsers across multiple CircleCI
-    # instances. Since by default this job launches two browsers, we run each browser
-    # in its own container instance.
-    # https://github.com/angular/material2/blob/7baeaa797b19da2d2998f0d26f6fede3c8a13714/test/karma.conf.js#L107-L110
-    parallelism: 2
-    environment:
-      # The Material unit tests also support launching the same browser multiple times by
-      # sharding individual specs across the defined multiple instances.
-      # See: https://github.com/angular/material2/blob/7baeaa797b19da2d2998f0d26f6fede3c8a13714/test/karma.conf.js#L113-L116
-      KARMA_PARALLEL_BROWSERS: 3
     steps:
       - *attach_workspace
       - *init_environment
-      - run:
-          name: "Cloning Material repository"
-          command: ./scripts/ci/clone_angular_material_repo.sh
+      # Although RBE is configured below for the Material repo, also setup RBE in the Angular repo
+      # to provision Angular's GCP token into the environment variables.
+      - *setup_bazel_remote_execution
+      # Restore the cache before cloning the repository because the clone script re-uses
+      # the restored repository if present. This reduces the amount of times the components
+      # repository needs to be cloned (this is slow and increases based on commits in the repo).
       - restore_cache:
-          # Material directory must be kept in sync with the `$MATERIAL_REPO_TMP_DIR` env variable.
-          # It needs to be hardcoded here, because env variables interpolation is not supported.
           keys:
-            - v2-angular-material-{{ checksum "/tmp/material2/yarn.lock" }}
-            - v2-angular-material-
+            - *material_unit_tests_cache_key
+            - *material_unit_tests_cache_key_short
       - run:
+          name: "Fetching Material repository"
+          command: ./scripts/ci/clone_angular_material_repo.sh
+      - run:
+          # Run yarn install to fetch the Bazel binaries as used in the Material repo.
           name: Installing Material dependencies.
           command: yarn --cwd ${MATERIAL_REPO_TMP_DIR} install --frozen-lockfile --non-interactive
-      # Save the cache before we run the Material unit tests script. This is necessary
-      # because we don't want to cache the node modules which have been modified to contain
-      # the attached Ivy package output.
       - save_cache:
-          # Material directory must be kept in sync with the `$MATERIAL_REPO_TMP_DIR` env variable.
-          # It needs to be hardcoded here, because env variables interpolation is not supported.
-          key: v2-angular-material-{{ checksum "/tmp/material2/yarn.lock" }}
+          key: *material_unit_tests_cache_key
           paths:
-            - "/tmp/material2/node_modules"
+            # Material directory must be kept in sync with the `$MATERIAL_REPO_TMP_DIR` env variable.
+            # It needs to be hardcoded here, because env variables interpolation is not supported.
+            - "/tmp/material2"
+      - run:
+          name: "Setup Bazel RBE remote execution in Material repo"
+          command: |
+            ./.circleci/setup-rbe.sh "${MATERIAL_REPO_TMP_DIR}/.bazelrc.user"
       - run:
           name: "Running Material unit tests"
           command: ./scripts/ci/run_angular_material_unit_tests.sh
@@ -666,6 +664,10 @@ jobs:
         # Run zone.js tools tests
       - run: yarn --cwd packages/zone.js promisetest
       - run: yarn --cwd packages/zone.js promisefinallytest
+      - run: yarn bazel build //packages/zone.js:npm_package &&
+             cp dist/bin/packages/zone.js/npm_package/dist/zone-mix.js ./packages/zone.js/test/extra/ &&
+             cp dist/bin/packages/zone.js/npm_package/dist/zone-patch-electron.js ./packages/zone.js/test/extra/ &&
+             yarn --cwd packages/zone.js electrontest
 
 workflows:
   version: 2
@@ -674,31 +676,41 @@ workflows:
       - setup
       - lint:
           requires:
-          - setup
+            - setup
       - test:
           requires:
-          - setup
+            - setup
       - test_ivy_aot:
           requires:
-          - setup
+            - setup
       - build-npm-packages:
           requires:
-          - setup
+            - setup
       - build-ivy-npm-packages:
           requires:
-          - setup
-      - test_aio:
-          requires:
-          - setup
-      - legacy-unit-tests-saucelabs:
-          requires:
-          - setup
-      - deploy_aio:
-          requires:
-            - test_aio
+            - setup
       - legacy-misc-tests:
           requires:
             - build-npm-packages
+      - legacy-unit-tests-saucelabs:
+          requires:
+            - setup
+      - test_saucelabs_bazel:
+          requires:
+            - setup
+          # This job is currently a PoC and a subset of `legacy-unit-tests-saucelabs`. Running on
+          # master only to avoid wasting resources.
+          #
+          # TODO: Run this job on all branches (including PRs) as soon as it is not a PoC.
+          filters:
+            branches:
+              only: master
+      - test_aio:
+          requires:
+            - setup
+      - deploy_aio:
+          requires:
+            - test_aio
       - test_aio_local:
           requires:
             - build-npm-packages
@@ -755,22 +767,6 @@ workflows:
           requires:
             - setup
 
-  saucelabs_tests:
-    jobs:
-      - setup
-      - test_saucelabs_bazel:
-          requires:
-            - setup
-    triggers:
-      - schedule:
-          # Runs the Saucelabs legacy tests every hour. We still want to run Saucelabs
-          # frequently as the caretaker needs up-to-date results when merging PRs or creating
-          # a new release. Also we primarily moved the Saucelabs job into a cronjob that doesn't
-          # run for PRs, in order to ensure that PRs are not affected by Saucelabs flakiness or
-          # incidents. This is still guaranteed (even if we run the job every hour).
-          cron: "0 * * * *"
-          filters: *publish_branches_filter
-
   aio_monitoring:
     jobs:
       - setup

.circleci/env.sh

@@ -77,7 +77,9 @@ setPublicVar SAUCE_READY_FILE_TIMEOUT 120
 # their separate build setups.
 setPublicVar MATERIAL_REPO_TMP_DIR "/tmp/material2"
 setPublicVar MATERIAL_REPO_URL "https://github.com/angular/material2.git"
-setPublicVar MATERIAL_REPO_BRANCH "ivy-2019"
+setPublicVar MATERIAL_REPO_BRANCH "master"
+# **NOTE**: When updating the commit SHA, also update the cache key in the CircleCI "config.yml".
+setPublicVar MATERIAL_REPO_COMMIT "701302dc482d7e4b77990b24e3b5ab330bbf1aa5"
 
 # Source `$BASH_ENV` to make the variables available immediately.
 source $BASH_ENV;

.circleci/setup-rbe.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -u -e -o pipefail
+
+# The path of the .bazelrc.user file to update should be passed as first parameter to this script.
+# This allows to setup RBE for both the Angular repo and the Material repo.
+bazelrc_user="$1"
+
+echo "Writing RBE configuration to ${bazelrc_user}"
+
+touch ${bazelrc_user}
+echo -e 'build --config=remote\n' >> ${bazelrc_user}
+echo -e 'build:remote --remote_accept_cached=true\n' >> ${bazelrc_user}
+echo "Reading from remote cache for bazel remote jobs."
+if [[ "$CI_PULL_REQUEST" == "false" ]]; then
+  echo -e 'build:remote --remote_upload_local_results=true\n' >> ${bazelrc_user}
+  echo "Uploading local build results to remote cache."
+else
+  echo -e 'build:remote --remote_upload_local_results=false\n' >> ${bazelrc_user}
+  echo "Not uploading local build results to remote cache."
+fi

.codefresh/Dockerfile.win-1809

@@ -82,6 +82,9 @@ FROM baseimage
 
 SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]
 
+# Install Bazel prereqs on Windows (https://docs.bazel.build/versions/master/install-windows.html)
+
+# Install MSYS2
 RUN Invoke-WebRequest -UseBasicParsing 'https://www.7-zip.org/a/7z1805-x64.exe' -OutFile 7z.exe; `
     Start-Process -FilePath 'C:\\7z.exe' -ArgumentList '/S', '/D=C:\\7zip0' -NoNewWindow -Wait; `
     Invoke-WebRequest -UseBasicParsing 'http://repo.msys2.org/distrib/x86_64/msys2-base-x86_64-20180531.tar.xz' -OutFile msys2.tar.xz; `
@@ -94,7 +97,10 @@ RUN Invoke-WebRequest -UseBasicParsing 'https://www.7-zip.org/a/7z1805-x64.exe'
     [Environment]::SetEnvironmentVariable('Path', $env:Path + ';C:\msys64\usr\bin', [System.EnvironmentVariableTarget]::Machine); `
     [Environment]::SetEnvironmentVariable('BAZEL_SH', 'C:\msys64\usr\bin\bash.exe', [System.EnvironmentVariableTarget]::Machine)
 
-# Install VS Build Tools
+# Install MSYS2 packages
+RUN C:\msys64\usr\bin\bash.exe -l -c \"pacman --needed --noconfirm -S zip unzip patch diffutils git\"
+
+# Install VS Build Tools (required to build C++ targets)
 RUN Invoke-WebRequest -UseBasicParsing https://download.visualstudio.microsoft.com/download/pr/df649173-11e9-4af2-8eb7-0eb02ba8958a/cadb5bdac41e55bb8f6a6b7c45273370/vs_buildtools.exe -OutFile vs_BuildTools.exe; `
     # Installer won't detect DOTNET_SKIP_FIRST_TIME_EXPERIENCE if ENV is used, must use setx /M
     setx /M DOTNET_SKIP_FIRST_TIME_EXPERIENCE 1; `
@@ -112,7 +118,7 @@ RUN Invoke-WebRequest -UseBasicParsing https://download.visualstudio.microsoft.c
     Remove-Item -Force -Recurse \"${Env:ProgramData}\Package Cache\"; `
     [Environment]::SetEnvironmentVariable('BAZEL_VC', \"${Env:ProgramFiles(x86)}\Microsoft Visual Studio\2019\BuildTools\VC\", [System.EnvironmentVariableTarget]::Machine)
 
-# Install Python
+# Install Python (required to build Python targets)
 RUN Invoke-WebRequest -UseBasicParsing https://www.python.org/ftp/python/3.5.1/python-3.5.1.exe -OutFile python-3.5.1.exe; `
     Start-Process python-3.5.1.exe -ArgumentList '/quiet InstallAllUsers=1 PrependPath=1' -Wait; `
     Remove-Item -Force python-3.5.1.exe

BUILD.bazel

@@ -18,15 +18,15 @@ filegroup(
     name = "web_test_bootstrap_scripts",
     # do not sort
     srcs = [
-        "@npm//node_modules/core-js:client/core.js",
-        "@npm//node_modules/zone.js:dist/zone.js",
-        "@npm//node_modules/zone.js:dist/zone-testing.js",
-        "@npm//node_modules/zone.js:dist/task-tracking.js",
+        "@npm//:node_modules/core-js/client/core.js",
+        "@npm//:node_modules/zone.js/dist/zone.js",
+        "@npm//:node_modules/zone.js/dist/zone-testing.js",
+        "@npm//:node_modules/zone.js/dist/task-tracking.js",
         "//:test-events.js",
         "//:shims_for_IE.js",
         # Including systemjs because it defines `__eval`, which produces correct stack traces.
-        "@npm//node_modules/systemjs:dist/system.src.js",
-        "@npm//node_modules/reflect-metadata:Reflect.js",
+        "@npm//:node_modules/systemjs/dist/system.src.js",
+        "@npm//:node_modules/reflect-metadata/Reflect.js",
     ],
 )
 
@@ -35,15 +35,15 @@ filegroup(
     srcs = [
         # We also declare the unminfied AngularJS files since these can be used for
         # local debugging (e.g. see: packages/upgrade/test/common/test_helpers.ts)
-        "@npm//node_modules/angular:angular.js",
-        "@npm//node_modules/angular:angular.min.js",
-        "@npm//node_modules/angular-1.5:angular.js",
-        "@npm//node_modules/angular-1.5:angular.min.js",
-        "@npm//node_modules/angular-1.6:angular.js",
-        "@npm//node_modules/angular-1.6:angular.min.js",
-        "@npm//node_modules/angular-mocks:angular-mocks.js",
-        "@npm//node_modules/angular-mocks-1.5:angular-mocks.js",
-        "@npm//node_modules/angular-mocks-1.6:angular-mocks.js",
+        "@npm//:node_modules/angular/angular.js",
+        "@npm//:node_modules/angular/angular.min.js",
+        "@npm//:node_modules/angular-1.5/angular.js",
+        "@npm//:node_modules/angular-1.5/angular.min.js",
+        "@npm//:node_modules/angular-1.6/angular.js",
+        "@npm//:node_modules/angular-1.6/angular.min.js",
+        "@npm//:node_modules/angular-mocks/angular-mocks.js",
+        "@npm//:node_modules/angular-mocks-1.5/angular-mocks.js",
+        "@npm//:node_modules/angular-mocks-1.6/angular-mocks.js",
     ],
 )
 

CHANGELOG.md

@@ -1,3 +1,52 @@
+<a name="8.1.3"></a>
+## [8.1.3](https://github.com/angular/angular/compare/8.1.2...8.1.3) (2019-07-30)
+
+
+### Bug Fixes
+
+* **elements:** handle falsy initial value ([#31604](https://github.com/angular/angular/issues/31604)) ([434b796](https://github.com/angular/angular/commit/434b796)), closes [angular/angular#30834](https://github.com/angular/angular/issues/30834)
+
+
+### Performance Improvements
+
+* **compiler:** avoid copying from prototype while cloning an object ([#31638](https://github.com/angular/angular/issues/31638)) ([1f3daa0](https://github.com/angular/angular/commit/1f3daa0)), closes [#31627](https://github.com/angular/angular/issues/31627)
+
+
+
+<a name="8.1.2"></a>
+## [8.1.2](https://github.com/angular/angular/compare/8.1.0...8.1.2) (2019-07-17)
+
+
+### Bug Fixes
+
+* use the correct WTF array to iterate over ([#31208](https://github.com/angular/angular/issues/31208)) ([4aed480](https://github.com/angular/angular/commit/4aed480))
+* **compiler-cli:** Return original sourceFile instead of redirected sourceFile from getSourceFile ([#26036](https://github.com/angular/angular/issues/26036)) ([13dbb98](https://github.com/angular/angular/commit/13dbb98)), closes [#22524](https://github.com/angular/angular/issues/22524)
+* **core:** export provider interfaces that are part of the public API types ([#31377](https://github.com/angular/angular/issues/31377)) ([bebf089](https://github.com/angular/angular/commit/bebf089)), closes [/github.com/angular/angular/pull/31377#discussion_r299254408](https://github.com//github.com/angular/angular/pull/31377/issues/discussion_r299254408) [/github.com/angular/angular/blob/9e34670b2/packages/core/src/di/interface/provider.ts#L365-L366](https://github.com//github.com/angular/angular/blob/9e34670b2/packages/core/src/di/interface/provider.ts/issues/L365-L366) [/github.com/angular/angular/blob/9e34670b2/packages/core/src/di/interface/provider.ts#L283-L284](https://github.com//github.com/angular/angular/blob/9e34670b2/packages/core/src/di/interface/provider.ts/issues/L283-L284) [/github.com/angular/angular/blob/9e34670b2/packages/core/src/di/index.ts#L23](https://github.com//github.com/angular/angular/blob/9e34670b2/packages/core/src/di/index.ts/issues/L23)
+
+
+
+<a name="8.1.1"></a>
+## [8.1.1](https://github.com/angular/angular/compare/8.1.0...8.1.1) (2019-07-10)
+
+
+### Bug Fixes
+
+* **core:** export provider interfaces that are part of the public API types ([#31377](https://github.com/angular/angular/issues/31377)) ([bebf089](https://github.com/angular/angular/commit/bebf089)), closes [/github.com/angular/angular/pull/31377#discussion_r299254408](https://github.com//github.com/angular/angular/pull/31377/issues/discussion_r299254408) [/github.com/angular/angular/blob/9e34670b2/packages/core/src/di/interface/provider.ts#L365-L366](https://github.com//github.com/angular/angular/blob/9e34670b2/packages/core/src/di/interface/provider.ts/issues/L365-L366) [/github.com/angular/angular/blob/9e34670b2/packages/core/src/di/interface/provider.ts#L283-L284](https://github.com//github.com/angular/angular/blob/9e34670b2/packages/core/src/di/interface/provider.ts/issues/L283-L284) [/github.com/angular/angular/blob/9e34670b2/packages/core/src/di/index.ts#L23](https://github.com//github.com/angular/angular/blob/9e34670b2/packages/core/src/di/index.ts/issues/L23)
+
+
+
+<a name="8.1.0"></a>
+# [8.1.0](https://github.com/angular/angular/compare/8.1.0-rc.0...8.1.0) (2019-07-02)
+
+
+### Bug Fixes
+
+* **core:** handle `undefined` meta in `injectArgs` ([#31333](https://github.com/angular/angular/issues/31333)) ([80ccd6c](https://github.com/angular/angular/commit/80ccd6c)), closes [CLI #14888](https://github.com/angular/angular-cli/issues/14888)
+* **service-worker:** cache opaque responses in data groups with `freshness` strategy ([#30977](https://github.com/angular/angular/issues/30977)) ([b0c3453](https://github.com/angular/angular/commit/b0c3453)), closes [#30968](https://github.com/angular/angular/issues/30968)
+* **service-worker:** cache opaque responses when requests exceeds timeout threshold ([#30977](https://github.com/angular/angular/issues/30977)) ([a9038ef](https://github.com/angular/angular/commit/a9038ef))
+
+
+
 <a name="8.1.0-rc.0"></a>
 # [8.1.0-rc.0](https://github.com/angular/angular/compare/8.1.0-next.3...8.1.0-rc.0) (2019-06-26)
 

WORKSPACE

@@ -18,8 +18,11 @@ load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 # Fetch rules_nodejs so we can install our npm dependencies
 http_archive(
     name = "build_bazel_rules_nodejs",
-    sha256 = "e04a82a72146bfbca2d0575947daa60fda1878c8d3a3afe868a8ec39a6b968bb",
-    urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/0.31.1/rules_nodejs-0.31.1.tar.gz"],
+    patch_args = ["-p1"],
+    # Patch https://github.com/bazelbuild/rules_nodejs/pull/903
+    patches = ["//tools:rollup_bundle_commonjs_ignoreGlobal.patch"],
+    sha256 = "6d4edbf28ff6720aedf5f97f9b9a7679401bf7fca9d14a0fff80f644a99992b4",
+    urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/0.32.2/rules_nodejs-0.32.2.tar.gz"],
 )
 
 # Check the bazel version and download npm dependencies
@@ -27,6 +30,7 @@ load("@build_bazel_rules_nodejs//:defs.bzl", "check_bazel_version", "check_rules
 
 # Bazel version must be at least the following version because:
 #   - 0.26.0 managed_directories feature added which is required for nodejs rules 0.30.0
+#   - 0.27.0 has a fix for managed_directories after `rm -rf node_modules`
 check_bazel_version(
     message = """
 You no longer need to install Bazel on your machine.
@@ -35,7 +39,7 @@ Try running `yarn bazel` instead.
     (If you did run that, check that you've got a fresh `yarn install`)
 
 """,
-    minimum_bazel_version = "0.26.0",
+    minimum_bazel_version = "0.27.0",
 )
 
 # The NodeJS rules version must be at least the following version because:
@@ -46,7 +50,10 @@ Try running `yarn bazel` instead.
 #   - 0.27.12 Adds NodeModuleSources provider for transtive npm deps support
 #   - 0.30.0 yarn_install now uses symlinked node_modules with new managed directories Bazel 0.26.0 feature
 #   - 0.31.1 entry_point attribute of nodejs_binary & rollup_bundle is now a label
-check_rules_nodejs_version(minimum_version_string = "0.31.1")
+#   - 0.32.0 yarn_install and npm_install no longer puts build files under symlinked node_modules
+#   - 0.32.1 remove override of @bazel/tsetse & exclude typescript lib declarations in node_module_library transitive_declarations
+#   - 0.32.2 resolves bug in @bazel/hide-bazel-files postinstall step
+check_rules_nodejs_version(minimum_version_string = "0.32.2")
 
 # Setup the Node.js toolchain
 node_repositories(
@@ -70,19 +77,7 @@ node_repositories(
 
 yarn_install(
     name = "npm",
-    data = [
-        "//:tools/npm/@angular_bazel/index.js",
-        "//:tools/npm/@angular_bazel/package.json",
-        "//:tools/postinstall-patches.js",
-        "//:tools/yarn/check-yarn.js",
-    ],
     package_json = "//:package.json",
-    # Don't install devDependencies, they are large and not used under Bazel
-    prod_only = True,
-    # Temporarily disable node_modules symlinking until the fix for
-    # https://github.com/bazelbuild/bazel/issues/8487 makes it into a
-    # future Bazel release
-    symlink_node_modules = False,
     yarn_lock = "//:yarn.lock",
 )
 

aio/content/cli/index.md

@@ -36,6 +36,14 @@ ng serve
 In your browser, open http://localhost:4200/ to see the new app run.
 When you use the [ng serve](cli/serve) command to build an app and serve it locally, the server automatically rebuilds the app and reloads the page when you change any of the source files.
 
+<div class="alert is-helpful">
+
+   When you run `ng new my-first-project` a new folder, named `my-first-project`, will be created in the current working directory. Since you want to be able to create files inside that folder, make sure you have sufficient rights in the current working directory before running the command.
+
+   If the current working directory is not the right place for your project, you can change to a more appropriate directory by running `cd <path-to-other-directory>` first.
+
+</div>
+
 ## Workspaces and project files
 
 The [ng new](cli/new) command creates an *Angular workspace* folder and generates a new app skeleton.
@@ -74,7 +82,7 @@ Command syntax is shown as follows:
 * Option names are prefixed with a double dash (--).
     Option aliases are prefixed with a single dash (-).
     Arguments are not prefixed.
-    For example: 
+    For example:
     <code-example format="." language="bash">
         ng build my-app -c production
     </code-example>
@@ -105,5 +113,5 @@ Schematic options are supplied to the command in the same format as immediate co
 
 ### Building with Bazel
 
-Optionally, you can configure the Angular CLI to use [Bazel](https://docs.bazel.build) as the build tool. For more information, see [Building with Bazel](guide/bazel). 
+Optionally, you can configure the Angular CLI to use [Bazel](https://docs.bazel.build) as the build tool. For more information, see [Building with Bazel](guide/bazel).
 

aio/content/examples/attribute-directives/e2e/src/app.e2e-spec.ts

@@ -25,8 +25,8 @@ describe('Attribute directives', () => {
     greenRb.click();
     browser.actions().mouseMove(highlightedEle).perform();
 
-    // Wait for up to 2s for the background color to be updated,
+    // Wait for up to 4s for the background color to be updated,
     // to account for slow environments (e.g. CI).
-    browser.wait(() => highlightedEle.getCssValue('background-color').then(c => c === lightGreen), 2000);
+    browser.wait(() => highlightedEle.getCssValue('background-color').then(c => c === lightGreen), 4000);
   });
 });

aio/content/examples/event-binding/src/app/app.component.ts

@@ -18,7 +18,7 @@ export class AppComponent {
   }
 
   deleteItem(item: Item) {
-    alert(`Delete the ${item}.`);
+    alert(`Delete the ${item.name}.`);
   }
 
   onClickMe(event?: KeyboardEvent) {

aio/content/examples/getting-started/src/app/cart/cart.component.html

@@ -16,16 +16,20 @@
 <!-- #enddocregion checkout-form-1 -->
 
   <div>
-    <label>Name</label>
-    <input type="text" formControlName="name">
+    <label for="name">
+      Name
+    </label>
+    <input id="name" type="text" formControlName="name">
   </div>
 
   <div>
-    <label>Address</label>
-    <input type="text" formControlName="address">
+    <label for="address">
+      Address
+    </label>
+    <input id="address" type="text" formControlName="address">
   </div>
 
   <button class="button" type="submit">Purchase</button>
-  
+
 <!-- #docregion checkout-form-1 -->
 </form>

aio/content/examples/i18n/src/app/app.component.ts

@@ -10,7 +10,6 @@ export class AppComponent {
   gender = 'female';
   fly = true;
   logo = 'https://angular.io/assets/images/logos/angular/angular.png';
-  heroes: string[] = ['Magneta', 'Celeritas', 'Dynama'];
   inc(i: number) {
     this.minutes = Math.min(5, Math.max(0, this.minutes + i));
   }

aio/content/examples/ngmodules/src/app/app.module.1.ts

@@ -0,0 +1,14 @@
+// imports
+import { BrowserModule } from '@angular/platform-browser';
+import { NgModule } from '@angular/core';
+
+import { AppComponent } from './app.component';
+
+// @NgModule decorator with its metadata
+@NgModule({
+  declarations: [AppComponent],
+  imports: [BrowserModule],
+  providers: [],
+  bootstrap: [AppComponent]
+})
+export class AppModule {}

aio/content/examples/rx-library/src/simple-creation.ts

@@ -7,9 +7,9 @@ import { from } from 'rxjs';
 const data = from(fetch('/api/endpoint'));
 // Subscribe to begin listening for async result
 data.subscribe({
- next(response) { console.log(response); },
- error(err) { console.error('Error: ' + err); },
- complete() { console.log('Completed'); }
+  next(response) { console.log(response); },
+  error(err) { console.error('Error: ' + err); },
+  complete() { console.log('Completed'); }
 });
 
 // #enddocregion promise

aio/content/examples/template-syntax/e2e/src/app.e2e-spec.ts

@@ -2,42 +2,49 @@
 
 import { browser, element, by } from 'protractor';
 
-// Not yet complete
-describe('Template Syntax', function () {
+// TODO Not yet complete
+describe('Template Syntax', () => {
 
-  beforeAll(function () {
+  beforeAll(() => {
     browser.get('');
   });
 
-  it('should be able to use interpolation with a hero', function () {
-    let heroInterEle = element.all(by.css('h2+p')).get(0);
+  it('should be able to use interpolation with a hero', () => {
+    const heroInterEle = element.all(by.css('h2+p')).get(0);
     expect(heroInterEle.getText()).toEqual('My current hero is Hercules');
   });
 
-  it('should be able to use interpolation with a calculation', function () {
-    let theSumEles = element.all(by.cssContainingText('h3~p', 'The sum of'));
+  it('should be able to use interpolation with a calculation', () => {
+    const theSumEles = element.all(by.cssContainingText('h3~p', 'The sum of'));
     expect(theSumEles.count()).toBe(2);
     expect(theSumEles.get(0).getText()).toEqual('The sum of 1 + 1 is 2');
     expect(theSumEles.get(1).getText()).toEqual('The sum of 1 + 1 is not 4');
   });
 
-  it('should be able to use class binding syntax', function () {
-    let specialEle = element(by.cssContainingText('div', 'Special'));
+  it('should be able to use class binding syntax', () => {
+    const specialEle = element(by.cssContainingText('div', 'Special'));
     expect(specialEle.getAttribute('class')).toMatch('special');
   });
 
-  it('should be able to use style binding syntax', function () {
-    let specialButtonEle = element(by.cssContainingText('div.special~button', 'button'));
+  it('should be able to use style binding syntax', () => {
+    const specialButtonEle = element(by.cssContainingText('div.special~button', 'button'));
     expect(specialButtonEle.getAttribute('style')).toMatch('color: red');
   });
 
   it('should two-way bind to sizer', async () => {
-    let div = element(by.css('div#two-way-1'));
-    let incButton = div.element(by.buttonText('+'));
-    let input = div.element(by.css('input'));
-    let initSize = await input.getAttribute('value');
+    const div = element(by.css('div#two-way-1'));
+    const incButton = div.element(by.buttonText('+'));
+    const input = div.element(by.css('input'));
+    const initSize = await input.getAttribute('value');
     incButton.click();
     expect(input.getAttribute('value')).toEqual((+initSize + 1).toString());
   });
-});
 
+  it('should change SVG rectangle\'s fill color on click', async () => {
+    const div = element(by.css('app-svg'));
+    const colorSquare = div.element(by.css('rect'));
+    const initialColor = await colorSquare.getAttribute('fill');
+    colorSquare.click();
+    expect(colorSquare.getAttribute('fill')).not.toEqual(initialColor);
+  });
+});

aio/content/examples/template-syntax/src/app/app.component.html

@@ -38,6 +38,7 @@
 <a href="#safe-navigation-operator">Safe navigation operator <i>?.</i></a><br>
 <a href="#non-null-assertion-operator">Non-null assertion operator <i>!.</i></a><br>
 <a href="#enums">Enums</a><br>
+<a href="#svg-templates">SVG Templates</a><br>
 
 <!-- Interpolation and expressions -->
 <hr><h2 id="interpolation">Interpolation</h2>
@@ -442,7 +443,7 @@ button</button>
 
 <!-- #docregion without-NgModel -->
 <input [value]="currentHero.name"
-       (input)="currentHero.name=$event.target.value" >
+       (input)="updateCurrentHeroName($event)">
 <!-- #enddocregion without-NgModel -->
 without NgModel
 <br>
@@ -752,7 +753,7 @@ bindon-ngModel
 
 <div>
   <!-- pipe price to USD and display the $ symbol -->
-  <label>Price: </label>{{product.price | currency:'USD':true}}
+  <label>Price: </label>{{product.price | currency:'USD':'symbol'}}
 </div>
 
 <a class="to-toc" href="#toc">top</a>
@@ -857,3 +858,9 @@ The null hero's name is {{nullHero && nullHero.name}}
 </p>
 
 <a class="to-toc" href="#toc">top</a>
+
+<hr><h2 id="svg-templates">SVG Templates</h2>
+<!-- #docregion svg-templates -->
+<app-svg></app-svg>
+<!-- #enddocregion svg-templates -->
+<a class="to-toc" href="#toc">top</a>

aio/content/examples/template-syntax/src/app/app.component.ts

@@ -5,7 +5,7 @@ import { AfterViewInit, Component, ElementRef, OnInit, QueryList, ViewChildren }
 
 import { Hero } from './hero';
 
-export enum Color {Red, Green, Blue};
+export enum Color {Red, Green, Blue}
 
 /**
  * Giant grab bag of stuff to drive the chapter
@@ -29,7 +29,7 @@ export class AppComponent implements AfterViewInit, OnInit {
     trackChanges(this.heroesWithTrackBy, () => this.heroesWithTrackByCount++);
   }
 
-  @ViewChildren('noTrackBy')   heroesNoTrackBy:   QueryList<ElementRef>;
+  @ViewChildren('noTrackBy')   heroesNoTrackBy: QueryList<ElementRef>;
   @ViewChildren('withTrackBy') heroesWithTrackBy: QueryList<ElementRef>;
 
   actionName = 'Go for it';
@@ -66,6 +66,10 @@ export class AppComponent implements AfterViewInit, OnInit {
 
   currentHero: Hero;
 
+  updateCurrentHeroName(event: Event) {
+    this.currentHero.name = (event.target as any).value;
+  }
+
   deleteHero(hero?: Hero) {
     this.alert(`Delete ${hero ? hero.name : 'the hero'}.`);
   }
@@ -105,13 +109,13 @@ export class AppComponent implements AfterViewInit, OnInit {
 
   get nullHero(): Hero { return null; }
 
-  onClickMe(event?: KeyboardEvent) {
-    let evtMsg = event ? ' Event target class is ' + (<HTMLElement>event.target).className  : '';
+  onClickMe(event?: MouseEvent) {
+    const evtMsg = event ? ' Event target class is ' + (event.target as HTMLElement).className  : '';
     this.alert('Click me.' + evtMsg);
   }
 
-  onSave(event?: KeyboardEvent) {
-    let evtMsg = event ? ' Event target is ' + (<HTMLElement>event.target).textContent : '';
+  onSave(event?: MouseEvent) {
+    const evtMsg = event ? ' Event target is ' + (event.target as HTMLElement).textContent : '';
     this.alert('Saved.' + evtMsg);
     if (event) { event.stopPropagation(); }
   }
@@ -140,9 +144,9 @@ export class AppComponent implements AfterViewInit, OnInit {
   setCurrentClasses() {
     // CSS classes: added/removed per current state of component properties
     this.currentClasses =  {
-      'saveable': this.canSave,
-      'modified': !this.isUnchanged,
-      'special':  this.isSpecial
+      saveable: this.canSave,
+      modified: !this.isUnchanged,
+      special:  this.isSpecial
     };
   }
   // #enddocregion setClasses
@@ -164,7 +168,7 @@ export class AppComponent implements AfterViewInit, OnInit {
   // #enddocregion trackByHeroes
 
   // #docregion trackById
-  trackById(index: number, item: any): number { return item['id']; }
+  trackById(index: number, item: any): number { return item.id; }
   // #enddocregion trackById
 }
 

aio/content/examples/template-syntax/src/app/app.module.ts

@@ -1,13 +1,14 @@
-import { NgModule }       from '@angular/core';
-import { BrowserModule }  from '@angular/platform-browser';
-import { FormsModule }    from '@angular/forms';
+import { NgModule } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { FormsModule } from '@angular/forms';
 
 import { AppComponent } from './app.component';
 import { BigHeroDetailComponent, HeroDetailComponent } from './hero-detail.component';
 import { ClickDirective, ClickDirective2 } from './click.directive';
-import { HeroFormComponent }      from './hero-form.component';
-import { heroSwitchComponents }   from './hero-switch.components';
-import { SizerComponent }         from './sizer.component';
+import { HeroFormComponent } from './hero-form.component';
+import { heroSwitchComponents } from './hero-switch.components';
+import { SizerComponent } from './sizer.component';
+import { SvgComponent } from './svg.component';
 
 @NgModule({
   imports: [
@@ -22,7 +23,8 @@ import { SizerComponent }         from './sizer.component';
     heroSwitchComponents,
     ClickDirective,
     ClickDirective2,
-    SizerComponent
+    SizerComponent,
+    SvgComponent
   ],
   bootstrap: [ AppComponent ]
 })

aio/content/examples/template-syntax/src/app/click.directive.ts

@@ -1,4 +1,4 @@
-/* tslint:disable use-output-property-decorator directive-class-suffix */
+/* tslint:disable directive-selector directive-class-suffix */
 // #docplaster
 import { Directive, ElementRef, EventEmitter, Output } from '@angular/core';
 

aio/content/examples/template-syntax/src/app/hero-form.component.ts

@@ -1,5 +1,5 @@
 import { Component, Input, ViewChild } from '@angular/core';
-import { NgForm }                      from '@angular/forms';
+import { NgForm } from '@angular/forms';
 
 import { Hero } from './hero';
 
@@ -15,10 +15,11 @@ export class HeroFormComponent {
   @Input() hero: Hero;
   @ViewChild('heroForm', {static: false}) form: NgForm;
 
+  // tslint:disable-next-line:variable-name
   private _submitMessage = '';
 
   get submitMessage() {
-    if (!this.form.valid) {
+    if (this.form && !this.form.valid) {
       this._submitMessage = '';
     }
     return this._submitMessage;

aio/content/examples/template-syntax/src/app/svg.component.css

@@ -0,0 +1,4 @@
+svg {
+  display: block;
+  width: 100%;
+}

aio/content/examples/template-syntax/src/app/svg.component.svg

@@ -0,0 +1,6 @@
+<svg>
+  <g>
+    <rect x="0" y="0" width="100" height="100" [attr.fill]="fillColor" (click)="changeColor()" />
+    <text x="120" y="50">click the rectangle to change the fill color</text>
+  </g>
+</svg>

aio/content/examples/template-syntax/src/app/svg.component.ts

@@ -0,0 +1,17 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-svg',
+  templateUrl: './svg.component.svg',
+  styleUrls: ['./svg.component.css']
+})
+export class SvgComponent {
+  fillColor = 'rgb(255, 0, 0)';
+
+  changeColor() {
+    const r = Math.floor(Math.random() * 256);
+    const g = Math.floor(Math.random() * 256);
+    const b = Math.floor(Math.random() * 256);
+    this.fillColor = `rgb(${r}, ${g}, ${b})`;
+  }
+}

aio/content/examples/toh-pt2/src/app/heroes/heroes.component.css

@@ -1,8 +1,4 @@
 /* HeroesComponent's private CSS styles */
-.selected {
-  background-color: #CFD8DC !important;
-  color: white;
-}
 .heroes {
   margin: 0 0 2em 0;
   list-style-type: none;
@@ -19,18 +15,18 @@
   height: 1.6em;
   border-radius: 4px;
 }
-.heroes li.selected:hover {
-  background-color: #BBD8DC !important;
-  color: white;
-}
 .heroes li:hover {
   color: #607D8B;
   background-color: #DDD;
   left: .1em;
 }
-.heroes .text {
-  position: relative;
-  top: -3px;
+.heroes li.selected {
+  background-color: #CFD8DC;
+  color: white;
+}
+.heroes li.selected:hover {
+  background-color: #BBD8DC;
+  color: white;
 }
 .heroes .badge {
   display: inline-block;

aio/content/examples/toh-pt2/src/app/heroes/heroes.component.ts

@@ -34,4 +34,7 @@ export class HeroesComponent implements OnInit {
     this.selectedHero = hero;
   }
   // #enddocregion on-select
+// #docregion component
 }
+// #enddocregion component
+

aio/content/examples/toh-pt3/src/app/heroes/heroes.component.css

@@ -1,8 +1,4 @@
 /* HeroesComponent's private CSS styles */
-.selected {
-  background-color: #CFD8DC !important;
-  color: white;
-}
 .heroes {
   margin: 0 0 2em 0;
   list-style-type: none;
@@ -19,18 +15,18 @@
   height: 1.6em;
   border-radius: 4px;
 }
-.heroes li.selected:hover {
-  background-color: #BBD8DC !important;
-  color: white;
-}
 .heroes li:hover {
   color: #607D8B;
   background-color: #DDD;
   left: .1em;
 }
-.heroes .text {
-  position: relative;
-  top: -3px;
+.heroes li.selected {
+  background-color: #CFD8DC;
+  color: white;
+}
+.heroes li.selected:hover {
+  background-color: #BBD8DC;
+  color: white;
 }
 .heroes .badge {
   display: inline-block;

aio/content/examples/toh-pt4/src/app/heroes/heroes.component.css

@@ -1,8 +1,4 @@
 /* HeroesComponent's private CSS styles */
-.selected {
-  background-color: #CFD8DC !important;
-  color: white;
-}
 .heroes {
   margin: 0 0 2em 0;
   list-style-type: none;
@@ -19,18 +15,18 @@
   height: 1.6em;
   border-radius: 4px;
 }
-.heroes li.selected:hover {
-  background-color: #BBD8DC !important;
-  color: white;
-}
 .heroes li:hover {
   color: #607D8B;
   background-color: #DDD;
   left: .1em;
 }
-.heroes .text {
-  position: relative;
-  top: -3px;
+.heroes li.selected {
+  background-color: #CFD8DC;
+  color: white;
+}
+.heroes li.selected:hover {
+  background-color: #BBD8DC;
+  color: white;
 }
 .heroes .badge {
   display: inline-block;
@@ -43,8 +39,6 @@
   left: -1px;
   top: -4px;
   height: 1.8em;
-  min-width: 16px;
-  text-align: right;
   margin-right: .8em;
   border-radius: 4px 0 0 4px;
 }

aio/content/examples/toh-pt5/src/app/app-routing.module.1.ts

@@ -0,0 +1,13 @@
+import { NgModule } from '@angular/core';
+import { RouterModule, Routes } from '@angular/router';
+import { HeroesComponent } from './heroes/heroes.component';
+
+const routes: Routes = [
+  { path: 'heroes', component: HeroesComponent }
+];
+
+@NgModule({
+  imports: [RouterModule.forRoot(routes)],
+  exports: [RouterModule]
+})
+export class AppRoutingModule { }

aio/content/examples/toh-pt5/src/app/app-routing.module.ts

@@ -7,9 +7,7 @@ import { RouterModule, Routes } from '@angular/router';
 // #docregion import-dashboard
 import { DashboardComponent }   from './dashboard/dashboard.component';
 // #enddocregion import-dashboard
-// #docregion heroes-route
 import { HeroesComponent }      from './heroes/heroes.component';
-// #enddocregion heroes-route
 // #docregion import-herodetail
 import { HeroDetailComponent }  from './hero-detail/hero-detail.component';
 // #enddocregion import-herodetail
@@ -39,7 +37,9 @@ const routes: Routes = [
   imports: [ RouterModule.forRoot(routes) ],
 // #enddocregion ngmodule-imports
 // #docregion v1
+// #docregion export-routermodule
   exports: [ RouterModule ]
+// #enddocregion export-routermodule
 })
 export class AppRoutingModule {}
 // #enddocregion , v1

aio/content/examples/toh-pt6/src/app/app.module.ts

@@ -23,13 +23,17 @@ import { HeroSearchComponent }  from './hero-search/hero-search.component';
 // #docregion v1
 import { MessagesComponent }    from './messages/messages.component';
 
+    // #docregion import-httpclientmodule
 @NgModule({
   imports: [
+    // #enddocregion import-httpclientmodule
     BrowserModule,
     FormsModule,
     AppRoutingModule,
     // #docregion in-mem-web-api-imports
+    // #docregion import-httpclientmodule
     HttpClientModule,
+    // #enddocregion import-httpclientmodule
 
     // The HttpClientInMemoryWebApiModule module intercepts HTTP requests
     // and returns simulated server responses.
@@ -38,7 +42,9 @@ import { MessagesComponent }    from './messages/messages.component';
       InMemoryDataService, { dataEncapsulation: false }
     )
     // #enddocregion in-mem-web-api-imports
+  // #docregion import-httpclientmodule
   ],
+  // #enddocregion import-httpclientmodule
   declarations: [
     AppComponent,
     DashboardComponent,
@@ -50,6 +56,9 @@ import { MessagesComponent }    from './messages/messages.component';
     // #docregion v1
   ],
   bootstrap: [ AppComponent ]
+// #docregion import-httpclientmodule
 })
+// #enddocregion import-httpclientmodule
+
 export class AppModule { }
 // #enddocregion , v1

aio/content/examples/toh-pt6/src/app/hero.service.ts

@@ -13,11 +13,6 @@ import { catchError, map, tap } from 'rxjs/operators';
 import { Hero } from './hero';
 import { MessageService } from './message.service';
 
-// #docregion http-options
-const httpOptions = {
-  headers: new HttpHeaders({ 'Content-Type': 'application/json' })
-};
-// #enddocregion http-options
 
 @Injectable({ providedIn: 'root' })
 export class HeroService {
@@ -26,6 +21,12 @@ export class HeroService {
   private heroesUrl = 'api/heroes';  // URL to web api
   // #enddocregion heroesUrl
 
+  // #docregion http-options
+  httpOptions = {
+    headers: new HttpHeaders({ 'Content-Type': 'application/json' })
+  };
+  // #enddocregion http-options
+
   // #docregion ctor
   constructor(
     private http: HttpClient,
@@ -96,7 +97,7 @@ export class HeroService {
   // #docregion addHero
   /** POST: add a new hero to the server */
   addHero (hero: Hero): Observable<Hero> {
-    return this.http.post<Hero>(this.heroesUrl, hero, httpOptions).pipe(
+    return this.http.post<Hero>(this.heroesUrl, hero, this.httpOptions).pipe(
       tap((newHero: Hero) => this.log(`added hero w/ id=${newHero.id}`)),
       catchError(this.handleError<Hero>('addHero'))
     );
@@ -109,7 +110,7 @@ export class HeroService {
     const id = typeof hero === 'number' ? hero : hero.id;
     const url = `${this.heroesUrl}/${id}`;
 
-    return this.http.delete<Hero>(url, httpOptions).pipe(
+    return this.http.delete<Hero>(url, this.httpOptions).pipe(
       tap(_ => this.log(`deleted hero id=${id}`)),
       catchError(this.handleError<Hero>('deleteHero'))
     );
@@ -119,7 +120,7 @@ export class HeroService {
   // #docregion updateHero
   /** PUT: update the hero on the server */
   updateHero (hero: Hero): Observable<any> {
-    return this.http.put(this.heroesUrl, hero, httpOptions).pipe(
+    return this.http.put(this.heroesUrl, hero, this.httpOptions).pipe(
       tap(_ => this.log(`updated hero id=${hero.id}`)),
       catchError(this.handleError<any>('updateHero'))
     );

aio/content/examples/upgrade-lazy-load-ajs/e2e/src/app.e2e-spec.ts

@@ -0,0 +1,79 @@
+import { browser, element, by, ExpectedConditions } from 'protractor';
+
+describe('Lazy Loading AngularJS Tests', function () {
+  const pageElements = {
+    homePageHref: element(by.cssContainingText('app-root nav a', 'Home')),
+    homePageParagraph: element(by.css('app-root app-home p')),
+    ajsUsersPageHref: element(by.cssContainingText('app-root nav a', 'Users')),
+    ajsUsersPageParagraph: element(by.css('app-root app-angular-js div p')),
+    notFoundPageHref: element(by.cssContainingText('app-root nav a', '404 Page')),
+    notFoundPageParagraph: element(by.css('app-root app-app404 p')),
+  };
+
+  beforeAll(async() => {
+    await browser.get('/');
+  });
+
+  it('should display \'Angular Home\' when visiting the home page', async() => {
+    await pageElements.homePageHref.click();
+
+    const paragraphText = await pageElements.homePageParagraph.getText();
+
+    expect(paragraphText).toEqual('Angular Home');
+  });
+
+  it('should display \'Users Page\' page when visiting the AngularJS page at /users', async() => {
+    await pageElements.ajsUsersPageHref.click();
+    await loadAngularJS();
+
+    const paragraphText = await pageElements.ajsUsersPageParagraph.getText();
+
+    expect(paragraphText).toEqual('Users Page');
+  });
+
+  it('should display \'Angular 404\' when visiting an invalid URL', async() => {
+    await pageElements.notFoundPageHref.click();
+
+    const paragraphText = await pageElements.notFoundPageParagraph.getText();
+
+    expect(paragraphText).toEqual('Angular 404');
+  });
+
+  // Workaround for https://github.com/angular/protractor/issues/4724
+  async function loadAngularJS() {
+    // Abort if `resumeBootstrap` has already occured
+    if (await browser.executeScript(`return '__TESTABILITY__NG1_APP_ROOT_INJECTOR__' in window;`)) {
+        return;
+    }
+
+    // Might have to re-insert the 'NG_DEFER_BOOTSTRAP!' if the name has been changed since protractor loaded the page
+    if (!await browser.executeScript('window.name.includes(\'NG_DEFER_BOOTSTRAP!\')')) {
+        await browser.executeScript('window.name = \'NG_DEFER_BOOTSTRAP!\' + name');
+    }
+
+    // Wait for the AngularJS bundle to download and initialize
+    await browser.wait(ExpectedConditions.presenceOf(element(by.css('app-root app-angular-js'))), 5000, 'AngularJS app');
+
+    // Run the protractor pre-bootstrap logic and resumeBootstrap
+    // Based on https://github.com/angular/protractor/blob/5.3.0/lib/browser.ts#L950-L969
+    {
+        let moduleNames = [];
+        for (const {name, script, args} of browser.mockModules_) {
+            moduleNames.push(name);
+            await browser.executeScriptWithDescription(script, 'add mock module ' + name, ...args);
+        }
+
+        await browser.executeScriptWithDescription(
+            // TODO: must manually assign __TESTABILITY__NG1_APP_ROOT_INJECTOR__ (https://github.com/angular/angular/issues/22723)
+            `window.__TESTABILITY__NG1_APP_ROOT_INJECTOR__ = angular.resumeBootstrap(arguments[0]) `
+            + `|| angular.element('app-angular-js').injector();`,
+            'resume bootstrap',
+            moduleNames
+        );
+    }
+
+    // Wait for the initial AngularJS page to finish loading
+    await browser.waitForAngular();
+  }
+});
+

aio/content/examples/upgrade-lazy-load-ajs/example-config.json

@@ -0,0 +1,3 @@
+{
+  "projectType": "cli-ajs"
+}

aio/content/examples/upgrade-lazy-load-ajs/src/app/angular-js/angular-js.component.ts

@@ -1,14 +1,22 @@
-import { Component, OnInit, ElementRef } from '@angular/core';
+import { Component, OnInit, OnDestroy, ElementRef } from '@angular/core';
 import { LazyLoaderService } from '../lazy-loader.service';
 
 @Component({
   selector: 'app-angular-js',
   template: '<div ng-view></div>'
 })
-export class AngularJSComponent implements OnInit {
-  constructor(private lazyLoader: LazyLoaderService, private elRef: ElementRef) {}
+export class AngularJSComponent implements OnInit, OnDestroy {
+  constructor(
+    private lazyLoader: LazyLoaderService,
+    private elRef: ElementRef
+  ) {}
 
   ngOnInit() {
     this.lazyLoader.load(this.elRef.nativeElement);
   }
+
+
+  ngOnDestroy() {
+    this.lazyLoader.destroy();
+  }
 }

aio/content/examples/upgrade-lazy-load-ajs/src/app/app.module.ts

@@ -19,7 +19,6 @@ import { App404Component } from './app404/app404.component';
     BrowserModule,
     AppRoutingModule
   ],
-  providers: [],
   bootstrap: [AppComponent]
 })
 export class AppModule { }

aio/content/examples/upgrade-lazy-load-ajs/src/app/lazy-loader.service.ts

@@ -1,23 +1,25 @@
 import { Injectable } from '@angular/core';
+import * as angular from 'angular';
 
 @Injectable({
   providedIn: 'root'
 })
 export class LazyLoaderService {
-  bootstrapped = false;
+  private app: angular.auto.IInjectorService;
 
   load(el: HTMLElement): void {
-    if (this.bootstrapped) {
-      return;
-    }
-
     import('./angularjs-app').then(app => {
       try {
-        app.bootstrap(el);
-        this.bootstrapped = true;
+        this.app = app.bootstrap(el);
       } catch (e) {
         console.error(e);
       }
     });
   }
+
+  destroy() {
+    if (this.app) {
+      this.app.get('$rootScope').$destroy();
+    }
+  }
 }

aio/content/guide/accessibility.md

@@ -0,0 +1,181 @@
+# Accessibility in Angular
+
+The web is used by a wide variety of people, including those who have visual or motor impairments.
+A variety of assistive technologies are available that make it much easier for these groups to
+interact with web-based software applications.
+In addition, designing an application to be more accessible generally improves the user experience for all users.
+
+For an in-depth introduction to issues and techniques for designing accessible applications, see the [Accessibility](https://developers.google.com/web/fundamentals/accessibility/#what_is_accessibility) section of the Google's [Web Fundamentals](https://developers.google.com/web/fundamentals/).
+
+This page discusses best practices for designing Angular applications that
+work well for all users, including those who rely on assistive technologies.
+
+## Accessibility attributes
+
+Building accessible web experience often involves setting [ARIA attributes](https://developers.google.com/web/fundamentals/accessibility/semantics-aria)
+to provide semantic meaning where it might otherwise be missing.
+Use [attribute binding](guide/template-syntax#attribute-binding) template syntax to control the values of accessibility-related attributes.
+
+When binding to ARIA attributes in Angular, you must use the `attr.` prefix, as the ARIA
+specification depends specifically on HTML attributes rather than properties on DOM elements.
+
+```html
+<!-- Use attr. when binding to an ARIA attribute -->
+<button [attr.aria-label]="myActionLabel">...</button>
+```
+
+Note that this syntax is only necessary for attribute _bindings_.
+Static ARIA attributes require no extra syntax.
+
+```html
+<!-- Static ARIA attributes require no extra syntax -->
+<button aria-label="Save document">...</button>
+```
+
+NOTE:
+
+<div class="alert is-helpful">
+
+   By convention, HTML attributes use lowercase names (`tabindex`), while properties use camelCase names (`tabIndex`).
+
+   See the [Template Syntax](https://angular.io/guide/template-syntax#html-attribute-vs-dom-property) guide for more background on the difference between attributes and properties.
+
+</div>
+
+
+## Angular UI components
+
+The [Angular Material](https://material.angular.io/) library, which is maintained by the Angular team, is a suite of reusable UI components that aims to be fully accessible.
+The [Component Development Kit (CDK)](https://material.angular.io/cdk/categories) includes the `a11y` package that provides tools to support various areas of accessibility.
+For example:
+
+* `LiveAnnouncer` is used to announce messages for screen-reader users using an `aria-live` region. See the W3C documentation for more information on [aria-live regions](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties#aria-live).
+
+* The `cdkTrapFocus` directive traps Tab-key focus within an element. Use it to create accessible experience for components like modal dialogs, where focus must be constrained.
+
+For full details of these and other tools, see the [Angular CDK accessibility overview](https://material.angular.io/cdk/a11y/overview).
+
+
+### Augmenting native elements
+
+Native HTML elements capture a number of standard interaction patterns that are important to accessibility.
+When authoring Angular components, you should re-use these native elements directly when possible, rather than re-implementing well-supported behaviors.
+
+For example, instead of creating a custom element for a new variety of button, you can create a component that uses an attribute selector with a native `<button>` element.
+This most commonly applies to `<button>` and `<a>`, but can be used with many other types of element.
+
+You can see examples of this pattern in Angular Material: [`MatButton`](https://github.com/angular/components/blob/master/src/material/button/button.ts#L66-L68), [`MatTabNav`](https://github.com/angular/components/blob/master/src/material/tabs/tab-nav-bar/tab-nav-bar.ts#L67), [`MatTable`](https://github.com/angular/components/blob/master/src/material/table/table.ts#L17).
+
+### Using containers for native elements
+
+Sometimes using the appropriate native element requires a container element.
+For example, the native `<input>` element cannot have children, so any custom text entry components need
+to wrap an `<input>` with additional elements.
+While you might just include the `<input>` in your custom component's template,
+this makes it impossible for users of the component to set arbitrary properties and attributes to the input element.
+Instead, you can create a container component that uses content projection to include the native control in the
+component's API.
+
+You can see [`MatFormField`](https://material.angular.io/components/form-field/overview) as an example of this pattern.
+
+## Case study: Building a custom progress bar
+
+The following example shows how to make a simple progress bar accessible by using host binding to control accessibility-related attributes.
+
+* The component defines an accessibility-enabled element with both the standard HTML attribute `role`, and ARIA attributes. The ARIA attribute `aria-valuenow` is bound to the user's input.
+
+   ```ts
+  import { Component, Input } from '@angular/core';
+   /**
+    * Example progressbar component.
+    */
+   @Component({
+     selector: 'example-progressbar',
+     template: `<div class="bar" [style.width.%]="value"></div>`,
+     styleUrls: ['./progress-bar.css'],
+     host: {
+       // Sets the role for this component to "progressbar"
+       role: 'progressbar',
+
+      // Sets the minimum and maximum values for the progressbar role.
+       'aria-valuemin': '0',
+       'aria-valuemax': '0',
+
+       // Binding that updates the current value of the progressbar.
+       '[attr.aria-valuenow]': 'value',
+     }
+   })
+   export class ExampleProgressbar  {
+     /** Current value of the progressbar. */
+     @Input() value: number = 0;
+   }
+   ```
+
+* In the template, the `aria-label` attribute ensures that the control is accessible to screen readers.
+
+   ```html
+   <label>
+      Enter an example progress value
+      <input type="number" min="0" max="100"
+         [value]="progress" (input)="progress = $event.target.value">
+   </label>
+
+   <!-- The user of the progressbar sets an aria-label to communicate what the progress means. -->
+   <example-progressbar [value]="progress" aria-label="Example of a progress bar">
+   </example-progressbar>
+   ```
+
+[See the full example in StackBlitz](https://stackblitz.com/edit/angular-kn5jdi?file=src%2Fapp%2Fapp.component.html).
+
+## Routing and focus management
+
+Tracking and controlling [focus](https://developers.google.com/web/fundamentals/accessibility/focus/) in a UI is an important consideration in designing for accessibility.
+When using Angular routing, you should decide where page focus goes upon navigation.
+
+To avoid relying solely on visual cues, you need to make sure your routing code updates focus after page navigation.
+Use the `NavigationEnd` event from the `Router` service to know when to update
+focus.
+
+The following example shows how to find and focus the main content header in the DOM after navigation.
+
+```ts
+
+router.events.pipe(filter(e => e instanceof NavigationEnd)).subscribe(() => {
+  const mainHeader = document.querySelector('#main-content-header')
+  if (mainHeader) {
+    mainHeader.focus();
+  }
+});
+
+```
+In a real application, the element that receives focus will depend on your specific
+application structure and layout.
+The focused element should put users in a position to immediately move into the main content that has just been routed into view.
+You should avoid situations where focus returns to the `body` element after a route change.
+
+
+## Additional resources
+
+* [Accessibility - Google Web Fundamentals](https://developers.google.com/web/fundamentals/accessibility)
+
+* [ARIA specification and authoring practices](https://www.w3.org/TR/wai-aria/)
+
+* [Material Design - Accessibility](https://material.io/design/usability/accessibility.html)
+
+* [Smashing Magazine](https://www.smashingmagazine.com/search/?q=accessibility)
+
+* [Inclusive Components](https://inclusive-components.design/)
+
+* [Accessibility Resources and Code Examples](https://dequeuniversity.com/resources/)
+
+* [W3C - Web Accessibility Initiative](https://www.w3.org/WAI/people-use-web/)
+
+* [Rob Dodson A11ycasts](https://www.youtube.com/watch?v=HtTyRajRuyY)
+
+* [Codelyzer](http://codelyzer.com/rules/) provides linting rules that can help you make sure your code meets accessibility standards.
+
+Books
+
+* "A Web for Everyone: Designing Accessible User Experiences", Sarah Horton and Whitney Quesenbery
+
+* "Inclusive Design Patterns", Heydon Pickering

aio/content/guide/app-shell.md

@@ -29,7 +29,7 @@ ng generate app-shell --client-project my-app --universal-project server-app
 
 After running this command you will notice that the `angular.json` configuration file has been updated to add two new targets, with a few other changes.
 
-<code-example format="." language="none" linenums="false">
+<code-example format="." language="json" linenums="false">
 "server": {
   "builder": "@angular-devkit/build-angular:server",
   "options": {

aio/content/guide/browser-support.md

@@ -53,7 +53,7 @@ Angular supports most recent browsers. This includes the following specific vers
       IE
     </td>
     <td>
-      11<br>10<br>9
+      11, 10, 9
     </td>
   </tr>
  <tr>
@@ -89,7 +89,7 @@ Angular supports most recent browsers. This includes the following specific vers
     </td>
 
     <td>
-      Nougat (7.0)<br>Marshmallow (6.0)<br>Lollipop (5.0, 5.1)<br>KitKat (4.4)
+      Nougat (7.0), Marshmallow (6.0), Lollipop (5.0, 5.1), KitKat (4.4)
     </td>
   </tr>
 
@@ -127,25 +127,27 @@ In Angular CLI version 8 and higher, applications are built using *differential
 This strategy allows you to continue to build your web application to support multiple browsers, but only load the necessary code that the browser needs.
 For more information about how this works, see [Differential Loading](guide/deployment#differential-loading) in the [Deployment guide](guide/deployment).
 
-## Enabling polyfills
+## Enabling polyfills with CLI projects
 
-[Angular CLI](cli) users enable polyfills through the `src/polyfills.ts` file that
-the CLI created with your project.
+The [Angular CLI](cli) provides support for polyfills.
+If you are not using the CLI to create your projects, see [Polyfill instructions for non-CLI users](#non-cli).
 
+When you create a project with the `ng new` command, a `src/polyfills.ts` configuration file is created as part of your project folder.
 This file incorporates the mandatory and many of the optional polyfills as JavaScript `import` statements.
 
-The npm packages for the _mandatory_ polyfills (such as `zone.js`) were installed automatically for you when you created your project and their corresponding `import` statements are ready to go. You probably won't touch these.
+* The npm packages for the [_mandatory_ polyfills](#polyfill-libs) (such as `zone.js`) are installed automatically for you when you create your project with `ng new`, and their corresponding `import` statements are already enabled in the `src/polyfills.ts` configuration file.
 
-But if you need an optional polyfill, you'll have to install its npm package.
-For example, [if you need the web animations polyfill](http://caniuse.com/#feat=web-animation), you could install it with `npm`, using the following command (or the `yarn` equivalent):
+* If you need an _optional_ polyfill, you must install its npm package, then uncomment or create the corresponding import statement in the `src/polyfills.ts` configuration file.
+
+For example, if you need the optional [web animations polyfill](http://caniuse.com/#feat=web-animation), you could install it with `npm`, using the following command (or the `yarn` equivalent):
 
 <code-example language="sh" class="code-shell">
-  # note that the web-animations-js polyfill is only here as an example
-  # it isn't a strict requirement of Angular anymore (more below)
+  # install the optional web animations polyfill
   npm install --save web-animations-js
 </code-example>
 
-Then open the `polyfills.ts` file and un-comment the corresponding `import` statement as in the following example:
+You can then add the import statement in the `src/polyfills.ts` file.
+For many polyfills, you can simply un-comment the corresponding `import` statement in the file, as in the following example.
 
 <code-example header="src/polyfills.ts">
   /**
@@ -155,23 +157,14 @@ Then open the `polyfills.ts` file and un-comment the corresponding `import` stat
   import 'web-animations-js';  // Run `npm install --save web-animations-js`.
 </code-example>
 
-If you can't find the polyfill you want in `polyfills.ts`,
-add it yourself, following the same pattern:
+If the polyfill you want is not already in `polyfills.ts` file, add the `import` statement by hand.
 
-1. install the npm package
-1. `import` the file in `polyfills.ts`
-
-<div class="alert is-helpful">
-
-Non-CLI users should follow the instructions [below](#non-cli).
-</div>
 
 {@a polyfill-libs}
 
 ### Mandatory polyfills
 These are the polyfills required to run an Angular application on each supported browser:
 
-
 <table>
 
   <tr style="vertical-align: top">
@@ -189,26 +182,13 @@ These are the polyfills required to run an Angular application on each supported
   <tr style="vertical-align: top">
 
     <td>
-      Chrome, Firefox, Edge, Safari 9+
+      Chrome, Firefox, Edge, <br>
+      Safari, Android, IE10+
     </td>
 
     <td>
 
-      [ES7/reflect](guide/browser-support#core-es7-reflect) (JIT only)
-
-    </td>
-
-  </tr>
-
-  <tr style="vertical-align: top">
-
-    <td>
-      Safari 7 & 8, IE10 & 11, Android 4.1+
-    </td>
-
-    <td>
-
-      [ES6](guide/browser-support#core-es6)
+      [ES2015](guide/browser-support#core-es6)
 
     </td>
 
@@ -222,7 +202,7 @@ These are the polyfills required to run an Angular application on each supported
 
     <td>
 
-      [ES6<br>classList](guide/browser-support#classlist)
+      ES2015<br>[classList](guide/browser-support#classlist)
 
     </td>
 
@@ -235,12 +215,6 @@ These are the polyfills required to run an Angular application on each supported
 
 Some features of Angular may require additional polyfills.
 
-For example, the animations library relies on the standard web animation API, which is only available in Chrome and Firefox today.
-(note that the dependency of web-animations-js in Angular is only necessary if `AnimationBuilder` is used.)
-
-Here are the features which may require additional polyfills:
-
-
 <table>
 
   <tr style="vertical-align: top">
@@ -263,31 +237,8 @@ Here are the features which may require additional polyfills:
 
     <td>
 
-      [JIT compilation](guide/aot-compiler).
-
-      Required to reflect for metadata.
-    </td>
-
-    <td>
-
-      [ES7/reflect](guide/browser-support#core-es7-reflect)
-
-    </td>
-
-    <td>
-      All current browsers. Enabled by default.
-      Can remove if you always use AOT and only use Angular decorators.
-    </td>
-
-  </tr>
-
-  <tr style="vertical-align: top">
-
-    <td>
-
-      [Animations](guide/animations)
-      <br>Only if `Animation Builder` is used within the application--standard
-      animation support in Angular doesn't require any polyfills (as of NG6).
+      [AnimationBuilder](api/animations/AnimationBuilder).
+      (Standard animation support does not require polyfills.)
 
     </td>
 
@@ -298,8 +249,9 @@ Here are the features which may require additional polyfills:
     </td>
 
     <td>
-      <p>If AnimationBuilder is used then the polyfill will enable scrubbing
-      support for IE/Edge and Safari (Chrome and Firefox support this natively).</p>
+      <p>If AnimationBuilder is used, enables scrubbing
+      support for IE/Edge and Safari.
+      (Chrome and Firefox support this natively).</p>
     </td>
 
   </tr>
@@ -308,15 +260,10 @@ Here are the features which may require additional polyfills:
 
     <td>
 
-    If you use the following deprecated i18n pipes:
-
-
+     If you use the following deprecated i18n pipes:
      [date](api/common/DeprecatedDatePipe),
-
      [currency](api/common/DeprecatedCurrencyPipe),
-
      [decimal](api/common/DeprecatedDecimalPipe),
-
      [percent](api/common/DeprecatedPercentPipe)
 
     </td>
@@ -337,9 +284,7 @@ Here are the features which may require additional polyfills:
 
     <td>
 
-       [NgClass](api/common/NgClass)
-
-       on SVG elements
+       [NgClass](api/common/NgClass) on SVG elements
     </td>
 
     <td>
@@ -358,9 +303,7 @@ Here are the features which may require additional polyfills:
 
     <td>
 
-      [Http](guide/http)
-
-      when sending and receiving binary data
+      [Http](guide/http) when sending and receiving binary data
     </td>
 
     <td>
@@ -383,9 +326,8 @@ Here are the features which may require additional polyfills:
 
     <td>
 
-      [Router](guide/router)
-
-      when using [hash-based routing](guide/router#appendix-locationstrategy-and-browser-url-styles)
+      [Router](guide/router) when using
+      [hash-based routing](guide/router#appendix-locationstrategy-and-browser-url-styles)
     </td>
 
     <td>
@@ -404,8 +346,9 @@ Here are the features which may require additional polyfills:
 
 
 
-### Suggested polyfills ##
-Below are the polyfills which are used to test the framework itself. They are a good starting point for an application.
+### Suggested polyfills
+
+The following polyfills are used to test the framework itself. They are a good starting point for an application.
 
 
 <table>
@@ -426,24 +369,6 @@ Below are the polyfills which are used to test the framework itself. They are a
 
   </tr>
 
-  <tr>
-
-    <td>
-
-      <a id='core-es7-reflect' href="https://github.com/zloirock/core-js/tree/v2/fn/reflect">ES7/reflect</a>
-
-    </td>
-
-    <td>
-      MIT
-    </td>
-
-    <td>
-      0.5KB
-    </td>
-
-  </tr>
-
   <tr>
 
     <td>
@@ -466,7 +391,7 @@ Below are the polyfills which are used to test the framework itself. They are a
 
     <td>
 
-      <a id='core-es6' href="https://github.com/zloirock/core-js">ES6</a>
+      <a id='core-es6' href="https://github.com/zloirock/core-js">ES2015</a>
 
     </td>
 
@@ -595,11 +520,14 @@ Below are the polyfills which are used to test the framework itself. They are a
 computed with the <a href="http://closure-compiler.appspot.com/home">closure compiler</a>.
 
 {@a non-cli}
+
 ## Polyfills for non-CLI users
 
-If you are not using the CLI, you should add your polyfill scripts directly to the host web page (`index.html`), perhaps like this.
+If you are not using the CLI, add your polyfill scripts directly to the host web page (`index.html`).
 
-<code-example header="src/index.html">
+For example:
+
+<code-example header="src/index.html" language="html" linenums="false">
   &lt;!-- pre-zone polyfills -->
   &lt;script src="node_modules/core-js/client/shim.min.js">&lt;/script>
   &lt;script src="node_modules/web-animations-js/web-animations.min.js">&lt;/script>

aio/content/guide/cheatsheet.md

@@ -185,8 +185,7 @@ is available to <code>declarations</code> of this module.</p>
 </td>
 </tr><tr>
 <td><code><b>@Injectable()</b><br>class MyService() {}</code></td>
-<td><p>Declares that a class has dependencies that should be injected into the constructor when the dependency injector is creating an instance of this class.
-</p>
+<td><p>Declares that a class can be provided and injected by other classes. Without this decorator, the compiler won't generate enough metadata to allow the class to be created properly when it's injected somewhere.</p>
 </td>
 </tr>
 </tbody></table>

aio/content/guide/deployment.md

@@ -153,16 +153,13 @@ The list is by no means exhaustive, but should provide you with a good starting
   (https://ngmilk.rocks/2015/03/09/angularjs-html5-mode-or-pretty-urls-on-apache-using-htaccess/):
 
   <code-example format=".">
-
     RewriteEngine On
     &#35 If an existing asset or directory is requested go to it as it is
     RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR]
     RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -d
-    RewriteRule ^ - [L]
-
+    RewriteRule ^ - [L]<br>
     &#35 If the requested resource doesn't exist, use index.html
     RewriteRule ^ /index.html
-
   </code-example>
 
 
@@ -170,18 +167,15 @@ The list is by no means exhaustive, but should provide you with a good starting
 [Front Controller Pattern Web Apps](https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#front-controller-pattern-web-apps),
 modified to serve `index.html`:
 
-  <code-example format=".">
-
-    try_files $uri $uri/ /index.html;
-
-  </code-example>
+  ```
+  try_files $uri $uri/ /index.html;
+  ```
 
 
 * [IIS](https://www.iis.net/): add a rewrite rule to `web.config`, similar to the one shown
 [here](http://stackoverflow.com/a/26152011/2116927):
 
-  <code-example format='.' linenums="false">
-
+  <code-example format='.' language="xml" linenums="false">
     &lt;system.webServer&gt;
       &lt;rewrite&gt;
         &lt;rules&gt;
@@ -196,7 +190,6 @@ modified to serve `index.html`:
         &lt;/rules&gt;
       &lt;/rewrite&gt;
     &lt;/system.webServer&gt;
-
   </code-example>
 
 
@@ -214,13 +207,11 @@ and to
 * [Firebase hosting](https://firebase.google.com/docs/hosting/): add a
 [rewrite rule](https://firebase.google.com/docs/hosting/url-redirects-rewrites#section-rewrites).
 
-  <code-example format=".">
-
+  <code-example format="." language="json">
     "rewrites": [ {
       "source": "**",
       "destination": "/index.html"
     } ]
-
   </code-example>
 
 {@a cors}
@@ -412,7 +403,7 @@ Differential loading, which is supported by default in Angular CLI version 8 and
 
 Differential loading is a strategy where the CLI builds two separate bundles as part of your deployed application.
 
-* The first bundle contains modern ES1015 syntax, takes advantage of built-in support in modern browsers, ships less polyfills, and results in a smaller bundle size.
+* The first bundle contains modern ES2015 syntax, takes advantage of built-in support in modern browsers, ships less polyfills, and results in a smaller bundle size.
 
 * The second bundle contains code in the old ES5 syntax, along with all necessary polyfills. This results in a larger bundle size, but supports older browsers.
 
@@ -446,23 +437,19 @@ When you create a production build using [`ng build --prod`](cli/build), the CLI
 The `index.html` file is also modified during the build process to include script tags that enable differential loading. See the sample output below from the `index.html` file produced during a build using `ng build`.
 
 <code-example language="html" format="." linenums="false">
-
-<!-- ... -->
-<body>
-  <app-root></app-root>
-  <script src="runtime-es2015.js" type="module"></script>
-  <script src="runtime-es5.js" nomodule></script>
-  <script src="polyfills-es2015.js" type="module"></script>
-  <script src="polyfills-es5.js" nomodule></script>
-  <script src="styles-es2015.js" type="module"></script>
-  <script src="styles-es5.js" nomodule></script>
-  <script src="vendor-es2015.js" type="module"></script>
-  <script src="vendor-es5.js" nomodule></script>
-  <script src="main-es2015.js" type="module"></script>
-  <script src="main-es5.js" nomodule></script>
-</body>
-<!-- ... -->
-
+&lt;body>
+  &lt;app-root>&lt;/app-root>
+  &lt;script src="runtime-es2015.js" type="module">&lt;/script>
+  &lt;script src="runtime-es5.js" nomodule>&lt;/script>
+  &lt;script src="polyfills-es2015.js" type="module">&lt;/script>
+  &lt;script src="polyfills-es5.js" nomodule>&lt;/script>
+  &lt;script src="styles-es2015.js" type="module">&lt;/script>
+  &lt;script src="styles-es5.js" nomodule>&lt;/script>
+  &lt;script src="vendor-es2015.js" type="module">&lt;/script>
+  &lt;script src="vendor-es5.js" nomodule>&lt;/script>
+  &lt;script src="main-es2015.js" type="module">&lt;/script>
+  &lt;script src="main-es5.js" nomodule>&lt;/script>
+&lt;/body>
 </code-example>
 
 Each script tag has a `type="module"` or `nomodule` attribute. Browsers with native support for ES modules only load the scripts with the `module` type attribute and ignore scripts with the `nomodule` attribute. Legacy browsers only load the scripts with the `nomodule` attribute, and ignore the script tags with the `module` type that load ES modules.
@@ -523,7 +510,7 @@ By default, legacy browsers such as IE 9-11 are ignored, and the compilation tar
 
 <div class="alert is-important">
 
-   To see which browsers are supported with the above configuration, see which settings meet to your browser support requirements, see the [Browserslist compatibility page](https://browserl.ist/?q=%3E+0.5%25%2C+last+2+versions%2C+Firefox+ESR%2C+Chrome+41%2C+not+dead%2C+not+IE+9-11).
+   To see which browsers are supported with the above configuration, see which settings meet to your browser support requirements, see the [Browserslist compatibility page](https://browserl.ist/?q=%3E+0.5%25%2C+last+2+versions%2C+Firefox+ESR%2C+not+dead%2C+not+IE+9-11).
 
 </div>
 
@@ -660,7 +647,7 @@ ng test --configuration es5
 
 ### Configuring the e2e command
 
-Create an ES5 serve configuration as explained above (link to the above serve section), and configuration an ES5 configuration for the E2E target.
+Create an [ES5 serve configuration](guide/deployment#configuring-serve-for-es5) as explained above, and configuration an ES5 configuration for the E2E target.
 
 <code-example language="json" format="." linenums="false">
 

aio/content/guide/deprecations.md

@@ -368,7 +368,7 @@ These two properties have subtle differences, so switching to `textContent` unde
 All of the `wtf*` APIs are deprecated and will be removed in a future version.
 
 {@a webworker-apps}
-### Running Angular applications in platform-webworker 
+### Running Angular applications in platform-webworker
 
 The `@angular/platform-*` packages enable Angular to be run in different contexts. For examples,
 `@angular/platform-server` enables Angular to be run on the server, and `@angular/platform-browser`
@@ -382,7 +382,7 @@ worker is not the best strategy for most applications.
 
 Going forward, we will focus our efforts related to web workers around their primary use case of
 offloading CPU-intensive, non-critical work needed for initial rendering (such as in-memory search
-and image processing). Learn more in the 
+and image processing). Learn more in the
 [guide to Using Web Workers with the Angular CLI](guide/web-worker).
 
 As of Angular version 8, all  `platform-webworker` APIs are deprecated.
@@ -465,3 +465,99 @@ For more information about using `@angular/common/http`, see the [HttpClient gui
 | `MockBackend` | [`HttpTestingController`](/api/common/http/testing/HttpTestingController) |
 | `MockConnection` | [`HttpTestingController`](/api/common/http/testing/HttpTestingController) |
 
+## Renderer to Renderer2 migration
+
+### Migration Overview
+
+The `Renderer` class has been marked as deprecated since Angular version 4. This section provides guidance on migrating from this deprecated API to the newer `Renderer2` API and what it means for your app.
+
+### Why should I migrate to Renderer2?
+
+The deprecated `Renderer` class has been removed in version 9 of Angular, so it's necessary to migrate to a supported API.  Using `Renderer2` is the recommended strategy because it supports a similar set of functionality to `Renderer`. The API surface is quite large (with 19 methods), but the schematic should simplify this process for your applications.
+
+### Is there action required on my end?
+
+No. The schematic should handle most cases with the exception of `Renderer.animate()` and `Renderer.setDebugInfo()`, which already aren’t supported.
+
+### What are the `__ngRendererX` methods? Why are they necessary?
+
+Some methods either don't have exact equivalents in `Renderer2`, or they correspond to more than one expression. For example, both renderers have a `createElement()` method, but they're not equal because a call such as `renderer.createElement(parentNode, namespaceAndName)` in the `Renderer` corresponds to the following block of code in `Renderer2`:
+
+```ts
+const [namespace, name] = splitNamespace(namespaceAndName);
+const el = renderer.createElement(name, namespace);
+if (parentNode) {
+  renderer.appendChild(parentNode, el);
+}
+return el;
+```
+
+Migration has to guarantee that the return values of functions and types of variables stay the same. To handle the majority of cases safely, the schematic declares helper functions at the bottom of the user's file. These helpers encapsulate your own logic and keep the replacements inside your code down to a single function call. Here's an example of how the `createElement()` migration looks:
+
+
+**Before:**
+
+```ts
+public createAndAppendElement() {
+  const el = this.renderer.createElement('span');
+  el.textContent = 'hello world';
+  return el;
+}
+```
+
+**After:**
+
+<code-example linenums=false>
+
+public createAndAppendElement() {
+  const el = __ngRendererCreateElement(this.renderer, this.element, 'span');
+  el.textContent = 'hello world';
+  return el;
+}
+// Generated code at the bottom of the file
+__ngRendererCreateElement(renderer: any, parentNode: any, nameAndNamespace: any) {
+  const [namespace, name] = __ngRendererSplitNamespace(namespaceAndName);
+  const el = renderer.createElement(name, namespace);
+  if (parentNode) {
+    renderer.appendChild(parentNode, el);
+  }
+  return el;
+}
+__ngRendererSplitNamespace(nameAndNamespace: any) {
+  // returns the split name and namespace
+}
+
+</code-example>
+
+When implementing these helper functions, the schematic ensures that they're only declared once per file and that their names are unique enough that there's a small chance of colliding with pre-existing functions in your code. The schematic also keeps their parameter types as `any` so that it doesn't have to insert extra logic that ensures that their values have the correct type.
+
+### I’m a library author. Should I run this migration?
+
+**Library authors should definitely use this migration to move away from the `Renderer`. Otherwise, the libraries won't work with applications built with version 9.**
+
+
+### Full list of method migrations
+
+The following table shows all methods that the migration maps from `Renderer` to `Renderer2`.
+
+|Renderer|Renderer2|
+|---|---|
+|`listen(renderElement, name, callback)`|`listen(renderElement, name, callback)`|
+|`setElementProperty(renderElement, propertyName, propertyValue)`|`setProperty(renderElement, propertyName, propertyValue)`|
+|`setText(renderNode, text)`|`setValue(renderNode, text)`|
+|`listenGlobal(target, name, callback)`|`listen(target, name, callback)`|
+|`selectRootElement(selectorOrNode, debugInfo?)`|`selectRootElement(selectorOrNode)`|
+|`createElement(parentElement, name, debugInfo?)`|`appendChild(parentElement, createElement(name))`|
+|`setElementStyle(el, style, value?)`|`value == null ? removeStyle(el, style) : setStyle(el, style, value)`
+|`setElementAttribute(el, name, value?)`|`attributeValue == null ? removeAttribute(el, name) : setAttribute(el, name, value)`
+|`createText(parentElement, value, debugInfo?)`|`appendChild(parentElement, createText(value))`|
+|`createTemplateAnchor(parentElement)`|`appendChild(parentElement, createComment(''))`|
+|`setElementClass(renderElement, className, isAdd)`|`isAdd ? addClass(renderElement, className) : removeClass(renderElement, className)`|
+|`projectNodes(parentElement, nodes)`|`for (let i = 0; i < nodes.length; i<ins></ins>) { appendChild(parentElement, nodes<i>); }`|
+|`attachViewAfter(node, viewRootNodes)`|`const parentElement = parentNode(node); const nextSibling = nextSibling(node); for (let i = 0; i < viewRootNodes.length; i<ins></ins>) { insertBefore(parentElement, viewRootNodes<i>, nextSibling);}`|
+|`detachView(viewRootNodes)`|`for (let i = 0; i < viewRootNodes.length; i<ins></ins>) {const node = viewRootNodes<i>; const parentElement = parentNode(node); removeChild(parentElement, node);}`|
+|`destroyView(hostElement, viewAllNodes)`|`for (let i = 0; i < viewAllNodes.length; i<ins></ins>) { destroyNode(viewAllNodes<i>); }`|
+|`setBindingDebugInfo()`|This function is a noop in `Renderer2`.|
+|`createViewRoot(hostElement)`|Should be replaced with a reference to `hostElement`|
+|`invokeElementMethod(renderElement, methodName, args?)`|`(renderElement as any)<methodName>.apply(renderElement, args);`|
+|`animate(element, startingStyles, keyframes, duration, delay, easing, previousPlayers?)`|Throws an error (same behavior as `Renderer.animate()`)|

aio/content/guide/entry-components.md

@@ -1,12 +1,5 @@
 # Entry Components
 
-#### Prerequisites:
-
-A basic understanding of the following concepts:
-* [Bootstrapping](guide/bootstrapping).
-
-<hr />
-
 An entry component is any component that Angular loads imperatively, (which means you’re not referencing it in the template), by type. You specify an entry component by bootstrapping it in an NgModule, or including it in a routing definition.
 
 <div class="alert is-helpful">

aio/content/guide/feature-modules.md

@@ -1,12 +1,6 @@
 # Feature Modules
 
-Feature modules are NgModules for the purpose of  organizing code.
-
-#### Prerequisites
-A basic understanding of the following:
-* [Bootstrapping](guide/bootstrapping).
-* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
-* [Frequently Used Modules](guide/frequent-ngmodules).
+Feature modules are NgModules for the purpose of organizing code.
 
 For the final sample app with a feature module that this page describes,
 see the <live-example></live-example>.

aio/content/guide/frequent-ngmodules.md

@@ -1,12 +1,5 @@
 # Frequently Used Modules
 
-#### Prerequisites
-
-A basic understanding of [Bootstrapping](guide/bootstrapping).
-
-
-<hr>
-
 An Angular app needs at least one module that serves as the root module.
 As you add features to your app, you can add them in modules.
 The following are frequently used Angular modules with examples

aio/content/guide/glossary.md

@@ -454,10 +454,9 @@ A form of property [data binding](#data-binding) in which a [template expression
 That text can be concatenated with neighboring text before it is assigned to an element property
 or displayed between element tags, as in this example.
 
-<code-example language="html" escape="html">
-  <label>My current hero is {{hero.name}}</label>
-
-</code-example>
+```html
+<label>My current hero is {{hero.name}}</label>
+```
 
 
 Read more about [interpolation](guide/template-syntax#interpolation) in [Template Syntax](guide/template-syntax).

aio/content/guide/lazy-loading-ngmodules.md

@@ -1,23 +1,13 @@
 # Lazy Loading Feature Modules
 
-#### Prerequisites
-A basic understanding of the following:
-* [Feature Modules](guide/feature-modules).
-* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
-* [Frequently Used Modules](guide/frequent-ngmodules).
-* [Types of Feature Modules](guide/module-types).
-* [Routing and Navigation](guide/router).
-
-For the final sample app with two lazy loaded modules that this page describes, see the
-<live-example></live-example>.
-
-<hr>
-
 ## High level view
 
 By default, NgModules are eagerly loaded, which means that as soon as the app loads, so do all the NgModules, whether or not they are immediately necessary. For large apps with lots of routes, consider lazy loading&mdash;a design pattern that loads NgModules as needed. Lazy loading helps keep initial
 bundle sizes smaller, which in turn helps decrease load times.
 
+For the final sample app with two lazy loaded modules that this page describes, see the
+<live-example></live-example>.
+
 There are three main steps to setting up a lazy loaded feature module:
 
 1. Create the feature module.

aio/content/guide/module-types.md

@@ -1,16 +1,5 @@
-
-
 # Types of Feature Modules
 
-#### Prerequisites
-
-A basic understanding of the following concepts:
-* [Feature Modules](guide/feature-modules).
-* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
-* [Frequently Used Modules](guide/frequent-ngmodules).
-
-<hr>
-
 There are five general categories of feature modules which
 tend to fall into the following groups:
 

aio/content/guide/ngmodule-api.md

@@ -1,15 +1,5 @@
 # NgModule API
 
-#### Prerequisites
-
-A basic understanding of the following concepts:
-* [Bootstrapping](guide/bootstrapping).
-* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
-
-<hr />
-
-## Purpose of `@NgModule`
-
 At a high level, NgModules are a way to organize Angular apps
 and they accomplish this through the metadata in the `@NgModule`
 decorator.

aio/content/guide/ngmodule-faq.md

@@ -1,13 +1,5 @@
 # NgModule FAQs
 
-
-#### Prerequisites:
-
-A basic understanding of the following concepts:
-* [NgModules](guide/ngmodules).
-
-<hr />
-
 NgModules help organize an application into cohesive blocks of functionality.
 
 This page answers the questions many developers ask about NgModule design and implementation.

aio/content/guide/ngmodule-vs-jsmodule.md

@@ -1,13 +1,9 @@
 # JavaScript Modules vs. NgModules
 
-#### Prerequisites
-A basic understanding of [JavaScript/ECMAScript modules](https://hacks.mozilla.org/2015/08/es6-in-depth-modules/).
-
-<hr>
-
 JavaScript and Angular use modules to organize code, and
 though they organize it differently, Angular apps rely on both.
 
+
 ## JavaScript modules
 
 In JavaScript, modules are individual files with JavaScript code in them. To make what’s in them available, you write an export statement, usually after the relevant code, like this:
@@ -24,6 +20,8 @@ import { AppComponent } from './app.component';
 
 JavaScript modules help you namespace, preventing accidental global variables.
 
+For more information on JavaScript modules, see [JavaScript/ECMAScript modules](https://hacks.mozilla.org/2015/08/es6-in-depth-modules/).
+
 ## NgModules
 
 <!-- KW-- perMisko: let's discuss. This does not answer the question why it is different. Also, last sentence is confusing.-->

aio/content/guide/ngmodules.md

@@ -1,13 +1,5 @@
 # NgModules
 
-#### Prerequisites
-
-A basic understanding of the following concepts:
-* [Bootstrapping](guide/bootstrapping).
-* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
-
-<hr>
-
 **NgModules** configure the injector and the compiler and help organize related things together.
 
 An NgModule is a class marked by the `@NgModule` decorator.
@@ -20,7 +12,6 @@ For an example app showcasing all the techniques that NgModules related pages
 cover, see the <live-example></live-example>. For explanations on the individual techniques, visit the relevant NgModule pages under the NgModules
 section.
 
-
 ## Angular modularity
 
 Modules are a great way to organize an application and extend it with capabilities from external libraries.
@@ -57,12 +48,13 @@ You then import these modules into the root module.
 
 ## The basic NgModule
 
-The [Angular CLI](cli) generates the following basic app module when creating a new app.
+The [Angular CLI](cli) generates the following basic `AppModule` when creating a new app.
 
-<code-example path="bootstrapping/src/app/app.module.ts" region="whole-ngmodule" header="src/app/app.module.ts" linenums="false">
+
+<code-example path="ngmodules/src/app/app.module.1.ts" header="src/app/app.module.ts (default AppModule)" linenums="false">	// @NgModule decorator with its metadata
 </code-example>
 
-At the top are the import statements. The next section is where you configure the `@NgModule` by stating what components and directives belong to it (`declarations`) as well as which other modules it uses (`imports`). This page builds on [Bootstrapping](guide/bootstrapping), which covers the structure of an NgModule in detail. If you need more information on the structure of an `@NgModule`, be sure to read [Bootstrapping](guide/bootstrapping).
+At the top are the import statements. The next section is where you configure the `@NgModule` by stating what components and directives belong to it (`declarations`) as well as which other modules it uses (`imports`). For more information on the structure of an `@NgModule`, be sure to read [Bootstrapping](guide/bootstrapping).
 
 <hr />
 

aio/content/guide/providers.md

@@ -1,16 +1,10 @@
 # Providers
 
-#### Prerequisites:
-* A basic understanding of [Bootstrapping](guide/bootstrapping).
-* Familiarity with [Frequently Used Modules](guide/frequent-ngmodules).
+A provider is an instruction to the DI system on how to obtain a value for a dependency. Most of the time, these dependencies are services that you create and provide.
 
 For the final sample app using the provider that this page describes,
 see the <live-example></live-example>.
 
-<hr>
-
-A provider is an instruction to the DI system on how to obtain a value for a dependency. Most of the time, these dependencies are services that you create and provide.
-
 ## Providing a service
 
 If you already have an app that was created with the [Angular CLI](cli), you can create a service using the [`ng generate`](cli/generate) CLI command in the root project directory. Replace _User_ with the name of your service.

aio/content/guide/sharing-ngmodules.md

@@ -1,18 +1,5 @@
 # Sharing Modules
 
-#### Prerequisites
-A basic understanding of the following:
-* [Feature Modules](guide/feature-modules).
-* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
-* [Frequently Used Modules](guide/frequent-ngmodules).
-* [Routing and Navigation](guide/router).
-* [Lazy loading modules](guide/lazy-loading-ngmodules).
-
-
-<!--* Components (#TBD) We don’t have a page just on the concept of components, but I think one would be helpful for beginners.-->
-
-<hr>
-
 Creating shared modules allows you to organize and streamline your code. You can put commonly
 used directives, pipes, and components into one module and then import just that module wherever
 you need it in other parts of your app.
@@ -54,7 +41,7 @@ to import `FormsModule`, `SharedModule` can still export
 way, you can give other modules access to `FormsModule` without
 having to import it directly into the `@NgModule` decorator.
 
-### Using components vs services from other modules.
+### Using components vs services from other modules
 
 There is an important distinction between using another module's component and
 using a service from another module. Import modules when you want to use

aio/content/guide/singleton-services.md

@@ -1,15 +1,10 @@
 # Singleton services
 
-#### Prerequisites:
-
-* A basic understanding of [Bootstrapping](guide/bootstrapping).
-* Familiarity with [Providers](guide/providers).
+A singleton service is a service for which only once instance exists in an app.
 
 For a sample app using the app-wide singleton service that this page describes, see the
 <live-example name="ngmodules"></live-example> showcasing all the documented features of NgModules.
 
-<hr />
-
 ## Providing a singleton service
 
 There are two ways to make a service a singleton in Angular:

aio/content/guide/static-query-migration.md

@@ -6,21 +6,21 @@ In version 9, the default setting for `@ViewChild` and `@ContentChild` queries i
 
 In preparation for this change, in version 8, we are migrating all applications and libraries to explicitly specify the resolution strategy for `@ViewChild` and `@ContentChild` queries.
 
-Specifically, this migration adds an explicit "static" flag that dictates when that query's results should be assigned. 
-Adding this flag will ensure your code works the same way when upgrading to version 9.   
+Specifically, this migration adds an explicit "static" flag that dictates when that query's results should be assigned.
+Adding this flag will ensure your code works the same way when upgrading to version 9.
 
 Before:
 
 ```
 // query results sometimes available in `ngOnInit`, sometimes in `ngAfterViewInit` (based on template)
-@ViewChild('foo') foo: ElementRef; 
+@ViewChild('foo') foo: ElementRef;
 ```
 
 After:
 
 ```
 // query results available in ngOnInit
-@ViewChild('foo', {static: true}) foo: ElementRef; 
+@ViewChild('foo', {static: true}) foo: ElementRef;
 
 OR
 
@@ -28,7 +28,7 @@ OR
 @ViewChild('foo', {static: false}) foo: ElementRef;
 ```
 
-Starting with version 9, the `static` flag will default to false. 
+Starting with version 9, the `static` flag will default to false.
 At that time, any `{static: false}` flags can be safely removed, and we will have a schematic that will update your code for you.
 
 Note: this flag only applies to `@ViewChild` and `@ContentChild` queries specifically, as `@ViewChildren` and `@ContentChildren` queries do not have a concept of static and dynamic (they are always resolved as if they are "dynamic").
@@ -38,50 +38,50 @@ Note: this flag only applies to `@ViewChild` and `@ContentChild` queries specifi
 {@a what-to-do-with-todo}
 ### What should I do if I see a `/* TODO: add static flag */` comment printed by the schematic?
 
-If you see this comment, it means that the schematic couldn't statically figure out the correct flag. In this case, you'll have to add the correct flag based on your application's behavior. 
+If you see this comment, it means that the schematic couldn't statically figure out the correct flag. In this case, you'll have to add the correct flag based on your application's behavior.
 For more information on how to choose, see the [next question](#how-do-i-choose).
 
 {@a how-do-i-choose}
 ### How do I choose which `static` flag value to use: `true` or `false`?
 
-In the official API docs, we have always recommended retrieving query results in [`ngAfterViewInit` for view queries](https://angular.io/api/core/ViewChild#description) and [`ngAfterContentInit` for content queries](https://angular.io/api/core/ContentChild#description). 
-This is because by the time those lifecycle hooks run, change detection has completed for the relevant nodes and we can guarantee that we have collected all the possible query results. 
+In the official API docs, we have always recommended retrieving query results in [`ngAfterViewInit` for view queries](https://angular.io/api/core/ViewChild#description) and [`ngAfterContentInit` for content queries](https://angular.io/api/core/ContentChild#description).
+This is because by the time those lifecycle hooks run, change detection has completed for the relevant nodes and we can guarantee that we have collected all the possible query results.
 
-Most applications will want to use `{static: false}` for the same reason. This setting will ensure query matches that are dependent on binding resolution (e.g. results inside `*ngIf`s or `*ngFor`s) will be found by the query. 
+Most applications will want to use `{static: false}` for the same reason. This setting will ensure query matches that are dependent on binding resolution (e.g. results inside `*ngIf`s or `*ngFor`s) will be found by the query.
 
 There are rarer cases where `{static: true}` flag might be necessary (see [answer here](#should-i-use-static-true)).
 
 {@a should-i-use-static-true}
 ### Is there a case where I should use `{static: true}`?
 
-This option was introduced to support creating embedded views on the fly. 
-If you need access to a `TemplateRef` in a query to create a view dynamically, you won't be able to do so in `ngAfterViewInit`. 
-Change detection has already run on that view, so creating a new view with the template will cause an `ExpressionHasChangedAfterChecked` error to be thrown. 
-In this case, you will want to set the `static` flag to `true` and create your view in `ngOnInit`. 
+This option was introduced to support creating embedded views on the fly.
+If you need access to a `TemplateRef` in a query to create a view dynamically, you won't be able to do so in `ngAfterViewInit`.
+Change detection has already run on that view, so creating a new view with the template will cause an `ExpressionHasChangedAfterChecked` error to be thrown.
+In this case, you will want to set the `static` flag to `true` and create your view in `ngOnInit`.
 In most other cases, the best practice is to use `{static: false}`.
 
 However, to facilitate the migration to version 8, you may also want to set the `static` flag to `true` if your component code already depends on the query results being available some time **before** `ngAfterViewInit` (for view queries) or `ngAfterContentInit` (for content queries).
-For example, if your component relies on the query results being populated in the `ngOnInit` hook or in `@Input` setters, you will need to either set the flag to `true` or re-work your component to adjust to later timing. 
+For example, if your component relies on the query results being populated in the `ngOnInit` hook or in `@Input` setters, you will need to either set the flag to `true` or re-work your component to adjust to later timing.
 
-Note: Selecting the static option means that query results nested in `*ngIf` or `*ngFor` will not be found by the query. 
-These results are only retrievable after change detection runs. 
+Note: Selecting the static option means that query results nested in `*ngIf` or `*ngFor` will not be found by the query.
+These results are only retrievable after change detection runs.
 
 {@a what-does-this-flag-mean}
 ### What does this flag mean and why is it necessary?
 
-The default behavior for queries has historically been undocumented and confusing, and has also commonly led to issues that are difficult to debug. 
-In version 9, we would like to make query behavior more consistent and simple to understand. 
+The default behavior for queries has historically been undocumented and confusing, and has also commonly led to issues that are difficult to debug.
+In version 9, we would like to make query behavior more consistent and simple to understand.
 
 To explain why, first it's important to understand how queries have worked up until now.
 
-Without the `static` flag, the compiler decided when each query would be resolved on a case-by-case basis. 
-All `@ViewChild`/`@ContentChild` queries were categorized into one of two buckets at compile time: "static" or "dynamic". 
+Without the `static` flag, the compiler decided when each query would be resolved on a case-by-case basis.
+All `@ViewChild`/`@ContentChild` queries were categorized into one of two buckets at compile time: "static" or "dynamic".
 This classification determined when query results would become available to users.
 
-- **Static queries** were queries where the result could be determined statically because the result didn't depend on runtime values like bindings. 
+- **Static queries** were queries where the result could be determined statically because the result didn't depend on runtime values like bindings.
 Results from queries classified as static were available before change detection ran for that view (accessible in `ngOnInit`).
 
-- **Dynamic queries** were queries where the result could NOT be determined statically because the result depended on runtime values (aka bindings). 
+- **Dynamic queries** were queries where the result could NOT be determined statically because the result depended on runtime values (aka bindings).
 Results from queries classified as dynamic were not available until after change detection ran for that view (accessible in `ngAfterContentInit` for content queries or `ngAfterViewInit` for view queries).
 
 For example, let's say we have a component, `Comp`. Inside it, we have this query:
@@ -96,8 +96,8 @@ and this template:
 <div foo></div>
 ```
 
-This `Foo` query would be categorized as static because at compile-time it's known that the `Foo` instance on the `<div>` is the correct result for the query. 
-Because the query result is not dependent on runtime values, we don't have to wait for change detection to run on the template before resolving the query. 
+This `Foo` query would be categorized as static because at compile-time it's known that the `Foo` instance on the `<div>` is the correct result for the query.
+Because the query result is not dependent on runtime values, we don't have to wait for change detection to run on the template before resolving the query.
 Consequently, results can be made available in `ngOnInit`.
 
 Let's say the query is the same, but the component template looks like this:
@@ -106,53 +106,62 @@ Let's say the query is the same, but the component template looks like this:
 <div foo *ngIf="showing"></div>
 ```
 
-With that template, the query would be categorized as a dynamic query. 
-We would need to know the runtime value of `showing` before determining what the correct results are for the query. 
+With that template, the query would be categorized as a dynamic query.
+We would need to know the runtime value of `showing` before determining what the correct results are for the query.
 As a result, change detection must run first, and results can only be made available in `ngAfterViewInit` or a setter for the query property.
 
-The effect of this implementation is that adding an `*ngIf` or `*ngFor` anywhere above a query match can change when that query's results become available. 
+The effect of this implementation is that adding an `*ngIf` or `*ngFor` anywhere above a query match can change when that query's results become available.
 
-Keep in mind that these categories only applied to `@ViewChild` and `@ContentChild` queries specifically. 
+Keep in mind that these categories only applied to `@ViewChild` and `@ContentChild` queries specifically.
 `@ViewChildren` and `@ContentChildren` queries did not have a concept of static and dynamic, so they were always resolved as if they were "dynamic".
 
-This strategy of resolving queries at different times based on the location of potential query matches has caused a lot of confusion. Namely: 
+This strategy of resolving queries at different times based on the location of potential query matches has caused a lot of confusion. Namely:
 
 * Sometimes query results are available in `ngOnInit`, but sometimes they aren't and it's not clear why (see [21800](https://github.com/angular/angular/issues/21800) or [19872](https://github.com/angular/angular/issues/19872)).
 
-* `@ViewChild` queries are resolved at a different time from `@ViewChildren` queries, and `@ContentChild` queries are resolved at a different time from `@ContentChildren` queries. 
+* `@ViewChild` queries are resolved at a different time from `@ViewChildren` queries, and `@ContentChild` queries are resolved at a different time from `@ContentChildren` queries.
 If a user turns a `@ViewChild` query into a `@ViewChildren` query, their code can break suddenly because the timing has shifted.
- 
+
 * Code depending on a query result can suddenly stop working as soon as an `*ngIf` or an `*ngFor` is added to a template.
 
-* A `@ContentChild` query for the same component will resolve at different times in the lifecycle for each usage of the component. 
+* A `@ContentChild` query for the same component will resolve at different times in the lifecycle for each usage of the component.
 This leads to buggy behavior where using a component with `*ngIf` is broken in subtle ways that aren't obvious to the component author.
 
-In version 9, we plan to simplify the behavior so all queries resolve after change detection runs by default. 
-The location of query matches in the template cannot affect when the query result will become available and suddenly break your code, and the default behavior is always the same. 
-This makes the logic more consistent and predictable for users. 
+In version 9, we plan to simplify the behavior so all queries resolve after change detection runs by default.
+The location of query matches in the template cannot affect when the query result will become available and suddenly break your code, and the default behavior is always the same.
+This makes the logic more consistent and predictable for users.
 
-That said, if an application does need query results earlier (for example, the query result is needed to create an embedded view), it's possible to add the `{static: true}` flag to explicitly ask for static resolution. 
+That said, if an application does need query results earlier (for example, the query result is needed to create an embedded view), it's possible to add the `{static: true}` flag to explicitly ask for static resolution.
 With this flag, users can indicate that they only care about results that are statically available and the query results will be populated before `ngOnInit`.
 
 {@a view-children-and-content-children}
 ### Does this change affect `@ViewChildren` or `@ContentChildren` queries?
 
-No, this change only affects `@ViewChild` and `@ContentChild` queries specifically. 
+No, this change only affects `@ViewChild` and `@ContentChild` queries specifically.
 `@ViewChildren` and `@ContentChildren` queries are already "dynamic" by default and don't support static resolution.
 
 {@a why-specify-static-false}
 ### ​Why do I have to specify `{static: false}`? Isn't that the default?
 
-The goal of this migration is to transition apps that aren't yet on version 9 to a query pattern that is compatible with version 9. 
-However, most applications use libraries, and it's likely that some of these libraries may not be upgraded to version 8 yet (and thus might not have the proper flags). 
-Since the application's version of Angular will be used for compilation, if we change the default, the behavior of queries in the library's components will change to the version 8 default and possibly break. 
-This way, an application's dependencies will behave the same way during the transition as they did in the previous version. 
+The goal of this migration is to transition apps that aren't yet on version 9 to a query pattern that is compatible with version 9.
+However, most applications use libraries, and it's likely that some of these libraries may not be upgraded to version 8 yet (and thus might not have the proper flags).
+Since the application's version of Angular will be used for compilation, if we change the default, the behavior of queries in the library's components will change to the version 8 default and possibly break.
+This way, an application's dependencies will behave the same way during the transition as they did in the previous version.
 
 In Angular version 9 and later, it will be safe to remove any `{static: false}` flags and we will do this cleanup for you in a schematic.
 
 {@a libraries}
 ###  Can I keep on using Angular libraries that haven’t yet updated to version 8 yet?
 
-Yes, absolutely! 
+Yes, absolutely!
 Because we have not changed the default query behavior in version 8 (i.e. the compiler still chooses a timing if no flag is set), when your application runs with a library that has not updated to version 8, the library will run the same way it did in version 7.
-This guarantees your app will work in version 8 even if libraries take longer to update their code.  
+This guarantees your app will work in version 8 even if libraries take longer to update their code.
+
+{@a update-library-to-use-static-flag}
+###  Can I update my library to version 8 by adding the `static` flag to view queries, while still being compatible with Angular version 7 apps?
+
+Yes, the Angular team's recommendation for libraries is to update to version 8 and add the `static` flag. Angular version 7 apps will continue to work with libraries that have this flag.
+
+However, if you update your library to Angular version 8 and want to take advantage of the new version 8 APIs, or you want more recent dependencies (such as Typescript or RxJS) your library will become incompatible with Angular version 7 apps. If your goal is to make your library compatible with Angular versions 7 and 8, you should not update your lib at all—except for `peerDependencies` in `package.json`.
+
+In general, the most efficient plan is for libraries to adopt a 6 month major version schedule and bump the major version after each Angular update. That way, libraries stay in the same release cadence as Angular.

aio/content/guide/structural-directives.md

@@ -275,53 +275,179 @@ In this example, the `[ngClass]="odd"` stays on the `<div>`.
 {@a microsyntax}
 
 
-### Microsyntax
+## Microsyntax
 
 The Angular microsyntax lets you configure a directive in a compact, friendly string.
 The microsyntax parser translates that string into attributes on the `<ng-template>`:
 
 * The `let` keyword declares a [_template input variable_](guide/structural-directives#template-input-variable)
 that you reference within the template. The input variables in this example are `hero`, `i`, and `odd`.
-The parser translates `let hero`, `let i`, and `let odd` into variables named,
+The parser translates `let hero`, `let i`, and `let odd` into variables named
 `let-hero`, `let-i`, and `let-odd`.
 
-* The microsyntax parser takes `of` and `trackBy`, title-cases them (`of` -> `Of`, `trackBy` -> `TrackBy`),
-and prefixes them with the directive's attribute name (`ngFor`), yielding the names `ngForOf` and `ngForTrackBy`.
-Those are the names of two `NgFor` _input properties_ .
+* The microsyntax parser title-cases all directives and prefixes them with the directive's
+attribute name, such as `ngFor`. For example, the `ngFor` input properties,
+`of` and `trackBy`, become `ngForOf` and `ngForTrackBy`, respectively.
 That's how the directive learns that the list is `heroes` and the track-by function is `trackById`.
 
 * As the `NgFor` directive loops through the list, it sets and resets properties of its own _context_ object.
-These properties include `index` and `odd` and a special property named `$implicit`.
+These properties can include, but aren't limited to, `index`, `odd`, and a special property
+named `$implicit`.
 
 * The `let-i` and `let-odd` variables were defined as `let i=index` and `let odd=odd`.
 Angular sets them to the current value of the context's `index` and `odd` properties.
 
 * The context property for `let-hero` wasn't specified.
 Its intended source is implicit.
-Angular sets `let-hero` to the value of the context's `$implicit` property
+Angular sets `let-hero` to the value of the context's `$implicit` property,
 which `NgFor` has initialized with the hero for the current iteration.
 
-* The [API guide](api/common/NgForOf "API: NgFor")
+* The [`NgFor` API guide](api/common/NgForOf "API: NgFor")
 describes additional `NgFor` directive properties and context properties.
 
-* `NgFor` is implemented by the `NgForOf` directive. Read more about additional `NgForOf` directive properties and context properties [NgForOf API reference](api/common/NgForOf).
+* The `NgForOf` directive implements `NgFor`. Read more about additional `NgForOf` directive properties and context properties in the [NgForOf API reference](api/common/NgForOf).
+
+### Writing your own structural directives
+
+These microsyntax mechanisms are also available to you when you write your own structural directives.
+For example, microsyntax in Angular allows you to write `<div *ngFor="let item of items">{{item}}</div>`
+instead of `<ng-template ngFor [ngForOf]="items"><div>{{item}}</div></ng-template`.
+The following sections provide detailed information on constraints, grammar,
+and translation of microsyntax.
+
+### Constraints
+
+Microsyntax must meet the following requirements:
+
+- It must be known ahead of time so that IDEs can parse it without knowing the underlying semantics of the directive or what directives are present.
+- It must translate to key-value attributes in the DOM.
+
+### Grammar
+
+When you write your own structural directives, use the following grammar:
+
+```
+*:prefix="( :let | :expression ) (';' | ',')? ( :let | :as | :keyExp )*"
+```
+
+The following tables describe each portion of the microsyntax grammar.
+
+<!-- What should I put in the table headers? -->
+
+<table>
+  <tr>
+    <th></th>
+    <th></th>
+  </tr>
+  <tr>
+    <td><code>prefix</code></td>
+    <td>HTML attribute key</td>
+  </tr>
+  <tr>
+    <td><code>key</code></td>
+    <td>HTML attribute key</td>
+  </tr>
+  <tr>
+    <td><code>local</code></td>
+    <td>local variable name used in the template</td>
+  </tr>
+  <tr>
+    <td><code>export</code></td>
+    <td>value exported by the directive under a given name</td>
+  </tr>
+  <tr>
+    <td><code>expression</code></td>
+    <td>standard Angular expression</td>
+  </tr>
+</table>
+
+<!-- The items in this table seem different. Is there another name for how we should describe them? -->
+<table>
+  <tr>
+    <th></th>
+  </tr>
+  <tr>
+    <td colspan="3"><code>keyExp = :key ":"? :expression ("as" :local)? ";"? </code></td>
+  </tr>
+  <tr>
+    <td colspan="3"><code>let = "let" :local "=" :export ";"?</code></td>
+  </tr>
+  <tr>
+    <td colspan="3"><code>as = :export "as" :local ";"?</code></td>
+  </tr>
+</table>
 
 
-These microsyntax mechanisms are available to you when you write your own structural directives.
+### Translation
+
+A microsyntax is translated to the normal binding syntax as follows:
+
+<!-- What to put in the table headers below? Are these correct?-->
+<table>
+  <tr>
+    <th>Microsyntax</th>
+    <th>Translation</th>
+  </tr>
+  <tr>
+    <td><code>prefix</code> and naked <code>expression</code></td>
+    <td><code>[prefix]="expression"</code></td>
+  </tr>
+  <tr>
+    <td><code>keyExp</code></td>
+    <td><code>[prefixKey] "expression"
+    (let-prefixKey="export")</code>
+    <br />
+    Notice that the <code>prefix</code>
+    is added to the <code>key</code>
+    </td>
+  </tr>
+  <tr>
+    <td><code>let</code></td>
+    <td><code>let-local="export"</code></td>
+  </tr>
+</table>
+
+### Microsyntax examples
+
+The following table demonstrates how Angular desugars microsyntax.
+
+<table>
+  <tr>
+    <th>Microsyntax</th>
+    <th>Desugared</th>
+  </tr>
+  <tr>
+    <td><code>*ngFor="let item of [1,2,3]"</code></td>
+    <td><code>&lt;ng-template ngFor let-item [ngForOf]="[1,2,3]"&gt;</code></td>
+  </tr>
+  <tr>
+    <td><code>*ngFor="let item of [1,2,3] as items; trackBy: myTrack; index as i"</code></td>
+    <td><code>&lt;ng-template ngFor let-item [ngForOf]="[1,2,3]" let-items="ngForOf" [ngForTrackBy]="myTrack" let-i="index"&gt;</code>
+    </td>
+  </tr>
+  <tr>
+    <td><code>*ngIf="exp"</code></td>
+    <td><code>&lt;ng-template [ngIf]="exp"&gt;</code></td>
+  </tr>
+  <tr>
+    <td><code>*ngIf="exp as value"</code></td>
+    <td><code>&lt;ng-template [ngIf]="exp" let-value="ngIf"&gt;</code></td>
+  </tr>
+</table>
+
 Studying the
 [source code for `NgIf`](https://github.com/angular/angular/blob/master/packages/common/src/directives/ng_if.ts "Source: NgIf")
 and [`NgForOf`](https://github.com/angular/angular/blob/master/packages/common/src/directives/ng_for_of.ts "Source: NgForOf")
 is a great way to learn more.
 
 
-
 {@a template-input-variable}
 
 
 {@a template-input-variables}
 
 
-### Template input variable
+## Template input variable
 
 A _template input variable_ is a variable whose value you can reference _within_ a single instance of the template.
 There are several such variables in this example: `hero`, `i`, and `odd`.
@@ -346,7 +472,7 @@ variable as the `hero` declared as `#hero`.
 {@a one-per-element}
 
 
-### One structural directive per host element
+## One structural directive per host element
 
 Someday you'll want to repeat a block of HTML but only when a particular condition is true.
 You'll _try_ to put both an `*ngFor` and an `*ngIf` on the same host element.

aio/content/guide/template-syntax.md

@@ -1796,7 +1796,7 @@ Though `@Input()` and `@Output()` often appear together in apps, you can use
 them separately. If the nested
 component is such that it only needs to send data to its parent, you wouldn't
 need an `@Input()`, only an `@Output()`. The reverse is also true in that if the
-child only needs to receive data from the parent, you'd only neeed `@Input()`.
+child only needs to receive data from the parent, you'd only need `@Input()`.
 
 </div>
 
@@ -2063,14 +2063,14 @@ to declare inputs and outputs, you can identify
 members in the `inputs` and `outputs` arrays
 of the directive metadata, as in this example:
 
-<code-example path="inputs-outputs/src/app/in-the-metadata/in-the-metadata.component.ts" region="metadata" header="src/app/app.component.html" linenums="false">
+<code-example path="inputs-outputs/src/app/in-the-metadata/in-the-metadata.component.ts" region="metadata" header="src/app/in-the-metadata/in-the-metadata.component.ts" linenums="false">
 </code-example>
 
 While declaring `inputs` and `outputs` in the `@Directive` and `@Component`
 metadata is possible, it is a better practice to use the `@Input()` and `@Output()`
 class decorators instead, as follows:
 
-<code-example path="inputs-outputs/src/app/input-output/input-output.component.ts" region="input-output" header="src/app/app.component.html" linenums="false">
+<code-example path="inputs-outputs/src/app/input-output/input-output.component.ts" region="input-output" header="src/app/input-output/input-output.component.ts" linenums="false">
 </code-example>
 
 See the [Decorate input and output properties](guide/styleguide#decorate-input-and-output-properties) section of the
@@ -2104,7 +2104,7 @@ offer a solution.
 Alias inputs and outputs in the metadata using a colon-delimited (`:`) string with
 the directive property name on the left and the public alias on the right:
 
-<code-example path="inputs-outputs/src/app/aliasing/aliasing.component.ts" region="alias" header="src/app/app.component.html" linenums="false">
+<code-example path="inputs-outputs/src/app/aliasing/aliasing.component.ts" region="alias" header="src/app/aliasing/aliasing.component.ts" linenums="false">
 </code-example>
 
 
@@ -2112,7 +2112,7 @@ the directive property name on the left and the public alias on the right:
 
 You can specify the alias for the property name by passing the alias name to the `@Input()`/`@Output()` decorator. The internal name remains as usual.
 
-<code-example path="inputs-outputs/src/app/aliasing/aliasing.component.ts" region="alias-input-output" header="src/app/app.component.html" linenums="false">
+<code-example path="inputs-outputs/src/app/aliasing/aliasing.component.ts" region="alias-input-output" header="src/app/aliasing/aliasing.component.ts" linenums="false">
 </code-example>
 
 
@@ -2273,3 +2273,27 @@ the component.
 </code-example>
 
 The `$any()` cast function works anywhere in a binding expression where a method call is valid.
+
+## SVG in templates
+
+It is possible to use SVG as valid templates in Angular. All of the template syntax below is
+applicable to both SVG and HTML. Learn more in the SVG [1.1](https://www.w3.org/TR/SVG11/) and
+[2.0](https://www.w3.org/TR/SVG2/) specifications.
+
+Why would you use SVG as template, instead of simply adding it as image to your application?
+
+When you use an SVG as the template, you are able to use directives and bindings just like with HTML
+templates. This means that you will be able to dynamically generate interactive graphics.
+
+Refer to the sample code snippet below for a syntax example:
+
+<code-example path="template-syntax/src/app/svg.component.ts" header="src/app/svg.component.ts">
+</code-example>
+
+Add the below code to your `svg.component.svg` file:
+
+<code-example path="template-syntax/src/app/svg.component.svg" header="src/app/svg.component.svg">
+</code-example>
+
+Here you can see the use of a `click()` event binding and the property binding syntax
+(`[attr.fill]="fillColor"`).

aio/content/guide/upgrade.md

@@ -868,6 +868,8 @@ As of Angular version 8, lazy loading code can be accomplished simply by using t
 
 The service uses the `import()` method to load your bundled AngularJS application lazily. This decreases the initial bundle size of your application as you're not loading code your user doesn't need yet. You also need to provide a way to _bootstrap_ the application manually after it has been loaded. AngularJS provides a way to manually bootstrap an application using the [angular.bootstrap()](https://docs.angularjs.org/api/ng/function/angular.bootstrap) method with a provided HTML element. Your AngularJS app should also expose a `bootstrap` method that bootstraps the AngularJS app.
 
+To ensure any necessary teardown is triggered in the AngularJS app, such as removal of global listeners, you also implement a method to call the `$rootScope.destroy()` method.
+
 <code-example path="upgrade-lazy-load-ajs/src/app/angularjs-app/index.ts" header="angularjs-app">
 </code-example>
 
@@ -886,7 +888,7 @@ In your Angular application, you need a component as a placeholder for your Angu
 <code-example path="upgrade-lazy-load-ajs/src/app/angular-js/angular-js.component.ts" header="src/app/angular-js/angular-js.component.ts">
 </code-example>
 
-When the Angular Router matches a route that uses AngularJS, the `AngularJSComponent` is rendered, and the content is rendered within the AngularJS [`ng-view`](https://docs.angularjs.org/api/ngRoute/directive/ngView) directive. 
+When the Angular Router matches a route that uses AngularJS, the `AngularJSComponent` is rendered, and the content is rendered within the AngularJS [`ng-view`](https://docs.angularjs.org/api/ngRoute/directive/ngView) directive. When the user navigates away from the route, the `$rootScope` is destroyed on the AngularJS application.
 
 ### Configure a custom route matcher for AngularJS routes
 

aio/content/guide/web-worker.md

@@ -27,7 +27,7 @@ Running this command will:
     // Create a new
     const worker = new Worker('./app.worker', { type: 'module' });
     worker.onmessage = ({ data }) => {
-      console.log('page got message: $\{data\}');
+      console.log(`page got message: ${data}`);
     };
     worker.postMessage('hello');
   } else {

aio/content/guide/workspace-config.md

@@ -157,7 +157,7 @@ The JSON schemas that the define the options and defaults for each of these defa
 
 ### Alternate build configurations
 
-By default, a `production` configuration is defined, and the `ng build` command has `--prod` option that builds using this configuration. The `production` configuration sets defaults that optimize the app in a number of ways, such bundling files, minimizing excess whitespace, removing comments and dead code, and rewriting code to use short, cryptic names ("minification").
+By default, a `production` configuration is defined, and the `ng build` command has `--prod` option that builds using this configuration. The `production` configuration sets defaults that optimize the app in a number of ways, such as bundling files, minimizing excess whitespace, removing comments and dead code, and rewriting code to use short, cryptic names ("minification").
 
 You can define and name additional alternate configurations (such as `stage`, for instance) appropriate to your development process. Some examples of different build configurations are `stable`, `archive` and `next` used by AIO itself, and the individual locale-specific configurations required for building localized versions of an app. For details, see [Internationalization (i18n)](guide/i18n#merge-aot).
 
@@ -227,3 +227,107 @@ The following example uses the `ignore` field to exclude certain files in the as
  { "glob": "**/*", "input": "src/assets/", "ignore": ["**/*.svg"], "output": "/assets/" },
 ]
 </code-example>
+
+{@a style-script-config}
+
+### Styles and scripts configuration
+
+An array entry for the `styles` and `scripts` options can be a simple path string, or an object that points to an extra entry-point file.
+The associated builder will load that file and its dependencies as a separate bundle during the build.
+With a configuration object, you have the option of naming the bundle for the entry point, using a `bundleName` field.
+
+The bundle is injected by default, but you can set `inject` to false to exclude the bundle from injection.
+For example, the following object values create and name a bundle that contains styles and scripts, and excludes it from injection:
+
+<code-example format="." language="json" linenums="false">
+
+   "styles": [
+     { "input": "src/external-module/styles.scss", "inject": false, "bundleName": "external-module" }
+   ],
+   "scripts": [
+     { "input": "src/external-module/main.js", "inject": false, "bundleName": "external-module" }
+   ]
+
+</code-example>
+
+You can mix simple and complex file references for styles and scripts.
+
+<code-example format="." language="json" linenums="false">
+
+"styles": [
+  "src/styles.css",
+  "src/more-styles.css",
+  { "input": "src/lazy-style.scss", "inject": false },
+  { "input": "src/pre-rename-style.scss", "bundleName": "renamed-style" },
+]
+
+</code-example>
+
+{@a style-preprocessor}
+
+#### Style preprocessor options
+
+In Sass and Stylus you can make use of the `includePaths` functionality for both component and global styles, which allows you to add extra base paths that will be checked for imports.
+
+To add paths, use the `stylePreprocessorOptions` option:
+
+<code-example format="." language="json" linenums="false">
+
+"stylePreprocessorOptions": {
+  "includePaths": [
+    "src/style-paths"
+  ]
+}
+
+</code-example>
+
+Files in that folder, such as `src/style-paths/_variables.scss`, can be imported from anywhere in your project without the need for a relative path:
+
+```ts
+// src/app/app.component.scss
+// A relative path works
+@import '../style-paths/variables';
+// But now this works as well
+@import 'variables';
+```
+
+Note that you will also need to add any styles or scripts to the `test` builder if you need them for unit tests.
+See also [Using runtime-global libraries inside your app](guide/using-libraries#using-runtime-global-libraries-inside-your-app).
+
+
+{@a optimize-and-srcmap}
+
+### Optimization and source map configuration
+
+The `optimization` and `sourceMap` command options are simple Boolean flags.
+You can supply an object as a configuration value for either of these to provide more detailed instruction.
+
+* The flag `--optimization="true"` applies to both scripts and styles. You can supply a value such as the following to apply optimization to one or the other:
+
+<code-example format="." language="json" linenums="false">
+
+   "optimization": { "scripts": true, "styles": false }
+
+</code-example>
+
+* The flag `--sourceMap="true"` outputs source maps for both scripts and styles.
+You can configure the option to apply to one or the other.
+You can also choose to output hidden source maps, or resolve vendor package source maps.
+For example:
+
+<code-example format="." language="json" linenums="false">
+
+   "sourceMaps": { "scripts": true, "styles": false, "hidden": true, "vendor": true }
+
+</code-example>
+
+<div class="alert is-helpful">
+
+   When using hidden source maps, source maps will not be referenced in the bundle.
+   These are useful if you only want source maps to map error stack traces in error reporting tools,
+   but don't want to expose your source maps in the browser developer tools.
+
+   For [Universal](guide/glossary#universal), you can reduce the code rendered in the HTML page by 
+   setting styles optimization to `true` and styles source maps to `false`.
+
+</div>

aio/content/marketing/resources.json

@@ -34,23 +34,12 @@
             "url": "https://dev.to/t/angular",
             "rev": true,
             "title": "DEV Community"
-          }
-        }
-      },
-      "Groups": {
-        "order": 2,
-        "resources": {
-          "sldkjfslkjfslkjdsklj": {
-            "desc": "Meetup in Barcelona, Spain. Express your motivations, share your ideas and play together creating awesome things in team.",
-            "rev": true,
-            "title": "Angular Beers",
-            "url": "http://www.meetup.com/AngularJS-Beers/"
           },
-          "sldkjfslkjfslkjdskzzzlj": {
-            "desc": "Angular Conferences and Angular Camps in Barcelona, Spain.",
+          "angular-in-depth" : {
+            "desc": "The place where advanced Angular concepts are explained",
+            "url": "https://blog.angularindepth.com",
             "rev": true,
-            "title": "Angular Camp",
-            "url": "http://angularcamp.org/"
+            "title": "Angular In Depth"
           }
         }
       },
@@ -62,7 +51,7 @@
             "logo": "",
             "rev": true,
             "title": "Adventures in Angular",
-            "url": "https://devchat.tv/adventures-in-angular"
+            "url": "https://devchat.tv/adv-in-angular/"
           },
           "sdlkfjsldfkj": {
             "desc": "Weekly video podcast hosted by Jeff Whelpley with all the latest and greatest happenings in the wild world of Angular.",
@@ -77,13 +66,6 @@
             "rev": true,
             "title": "Happy Angular Podcast",
             "url": "https://happy-angular.de/"
-          },
-          "sldkfjsldjf": {
-            "desc": "The live broadcast podcast all about JavaScript",
-            "logo": "",
-            "rev": true,
-            "title": "Javascript Air",
-            "url": "https://javascriptair.com/"
           }
         }
       }
@@ -95,40 +77,26 @@
       "Cross-Platform Development": {
         "order": 5,
         "resources": {
-          "a2b": {
-            "desc": "Angular and React Native to build applications for Android and iOS",
-            "logo": "",
-            "rev": true,
-            "title": "ReactNative",
-            "url": "http://angular.github.io/react-native-renderer/"
-          },
           "a3b": {
             "desc": "Ionic offers a library of mobile-optimized HTML, CSS and JS components and tools for building highly interactive native and progressive web apps.",
             "logo": "http://ionicframework.com/img/ionic-logo-white.svg",
             "rev": true,
             "title": "Ionic",
-            "url": "http://ionicframework.com/docs/v2/"
+            "url": "https://ionicframework.com/docs"
           },
           "a4b": {
             "desc": "Electron Platform for Angular.",
             "logo": "",
             "rev": true,
             "title": "Electron",
-            "url": "http://github.com/angular/angular-electron"
+            "url": "https://github.com/maximegris/angular-electron"
           },
           "ab": {
             "desc": "NativeScript is how you build cross-platform, native iOS and Android apps with Angular and TypeScript. Get 100% access to native APIs via JavaScript and reuse of packages from NPM, CocoaPods and Gradle. Open source and backed by Telerik.​​​",
             "logo": "",
             "rev": true,
             "title": "NativeScript",
-            "url": "https://github.com/NativeScript/nativescript-angular"
-          },
-          "ab5": {
-            "desc": "An Universal Windows App (uwp) powered by Angular",
-            "logo": "",
-            "rev": true,
-            "title": "Windows (UWP)",
-            "url": "http://github.com/preboot/angular2-universal-windows-app"
+            "url": "https://docs.nativescript.org/angular/start/introduction"
           }
         }
       },
@@ -139,7 +107,13 @@
             "desc": "Reactive Extensions for Angular",
             "rev": true,
             "title": "ngrx",
-            "url": "http://github.com/ngrx"
+            "url": "https://ngrx.io/"
+          },
+          "ngxs": {
+            "desc": "NGXS is a state management pattern + library for Angular. NGXS is modeled after the CQRS pattern popularly implemented in libraries like Redux and NgRx but reduces boilerplate by using modern TypeScript features such as classes and decorators.",
+            "rev": true,
+            "title": "NGXS",
+            "url": "https://ngxs.io/"
           },
           "ab": {
             "desc": "The official library for Firebase and Angular",
@@ -153,21 +127,14 @@
             "logo": "http://www.angular-meteor.com/images/logo.png",
             "rev": true,
             "title": "Meteor",
-            "url": "http://www.angular-meteor.com/angular2"
+            "url": "https://github.com/urigo/angular-meteor"
           },
           "ab3": {
             "desc": "Apollo is a data stack for modern apps, built with GraphQL.",
             "logo": "http://docs.apollostack.com/logo/large.png",
             "rev": true,
             "title": "Apollo",
-            "url": "http://docs.apollostack.com/apollo-client/angular2.html"
-          },
-          "ab4": {
-            "desc": "Angular Commerce is a solution for building modern e-commerce applications with power of Google Firebase. Set of components is design agnostic and allows to easily extend functionality.",
-            "logo": "",
-            "rev": true,
-            "title": "AngularCommerce",
-            "url": "https://github.com/NodeArt/angular-commerce"
+            "url": "https://www.apollographql.com/docs/angular/"
           },
           "ngx-api-utils": {
             "desc": "ngx-api-utils is a lean library of utilities and helpers to quickly integrate any HTTP API (REST, Ajax, and any other) with Angular.",
@@ -219,12 +186,6 @@
       "Tooling": {
         "order": 2,
         "resources": {
-          "-KLIzHfBEr1qMMUDxfq3": {
-            "desc": "Generate an Angular CRUD application from an existing database schema",
-            "rev": true,
-            "title": "Celerio Angular Quickstart",
-            "url": "https://github.com/jaxio/celerio-angular-quickstart"
-          },
           "a1": {
             "desc": "A Google Chrome Dev Tools extension for debugging Angular applications.",
             "logo": "https://augury.angular.io/images/augury-logo.svg",
@@ -259,13 +220,6 @@
             "title": "Codelyzer",
             "url": "https://github.com/mgechev/codelyzer"
           },
-          "e1": {
-            "desc": "This package provides facilities for developers building Angular applications on ASP.NET.",
-            "logo": "",
-            "rev": true,
-            "title": "Universal for ASP.NET",
-            "url": "https://github.com/aspnet/nodeservices"
-          },
           "f1": {
             "desc": "This tool generates dedicated documentation for Angular applications.",
             "logo": "",
@@ -273,13 +227,6 @@
             "title": "Compodoc",
             "url": "https://github.com/compodoc/compodoc"
           },
-          "ncg": {
-            "desc": "Generate several types of CRUD apps complete with e2e testing using template-sets for Angular, Material Design, Bootstrap, Kendo UI, Ionic, ...",
-            "logo": "https://avatars3.githubusercontent.com/u/27976684",
-            "rev": true,
-            "title": "NinjaCodeGen - Angular CRUD Generator",
-            "url": "https://ninjaCodeGen.com"
-          },
           "angular-playground": {
             "desc": "UI development environment for building, testing, and documenting Angular applications.",
             "rev": true,
@@ -330,12 +277,6 @@
             "title": "Clarity Design System",
             "url": "https://vmware.github.io/clarity/"
           },
-          "-KLIzI9BTvvP_hUwutXk": {
-            "desc": "UI components for Angular using Semantic UI",
-            "rev": true,
-            "title": "Semantic UI",
-            "url": "https://github.com/vladotesanovic/ngSemantic"
-          },
           "-KMVB8P4TDfht8c0L1AE": {
             "desc": "The Angular version of the Angular UI Bootstrap library. This library is being built from scratch in Typescript using the Bootstrap 4 CSS framework.",
             "rev": true,
@@ -520,12 +461,6 @@
       "Books": {
         "order": 1,
         "resources": {
-          "-KLI8vJ0ZkvWhqPembZ7": {
-            "desc": "A guide that helps developers get up to speed quickly on Angular and its accompanying technologies.",
-            "rev": true,
-            "title": "How to Get Started and Productive in Angular Fast",
-            "url": "http://www.amazon.com/How-Started-Productive-Angular-Fast-ebook/dp/B01D3B0ET4/ref=sr_1_1_twi_kin_2?ie=UTF8&qid=1462381159&sr=8-1"
-          },
           "-KLIzGEp8Mh5W-FkiQnL": {
             "desc": "Your quick, no-nonsense guide to building real-world apps with Angular",
             "rev": true,
@@ -536,25 +471,7 @@
             "desc": "More than 15 books from O'Reilly about Angular",
             "rev": true,
             "title": "O'Reilly Media",
-            "url": "https://ssearch.oreilly.com/?q=angular+2&x=0&y=0"
-          },
-          "8ab": {
-            "desc": "This books shows all the steps necessary for the development of SPA (Single Page Application) applications with the brand new Angular",
-            "rev": true,
-            "title": "Practical Angular",
-            "url": "https://leanpub.com/practical-angular-2"
-          },
-          "a2b": {
-            "desc": "Publications and books from Manning about Angular",
-            "rev": true,
-            "title": "Manning Publications",
-            "url": "https://www.manning.com/search?q=angular"
-          },
-          "a4b": {
-            "desc": "From getting started with the Angular toolchain to writing applications with scalable front end architectures, this book walks you through everything you need to know.",
-            "rev": true,
-            "title": "Rangle's Angular Training Book",
-            "url": "http://ngcourse.rangle.io/"
+            "url": "https://ssearch.oreilly.com/?q=angular"
           },
           "a5b": {
             "desc": "The in-depth, complete, and up-to-date book on Angular. Become an Angular expert today.",
@@ -562,12 +479,6 @@
             "title": "ng-book",
             "url": "https://www.ng-book.com/2/"
           },
-          "a6b": {
-            "desc": "A Practical Introduction to the new Web Development Platform Angular",
-            "rev": true,
-            "title": "Angular Book",
-            "url": "https://leanpub.com/angular2-book"
-          },
           "a7b": {
             "desc": "This ebook will help you getting the philosophy of the framework: what comes from 1.x, what has been introduced and why",
             "rev": true,
@@ -578,13 +489,13 @@
             "desc": "More than 10 books from Packt Publishing about Angular",
             "rev": true,
             "title": "Packt Publishing",
-            "url": "https://www.packtpub.com/all/?search=angular%202#"
+            "url": "https://www.packtpub.com/catalogsearch/result/?q=angular"
           },
           "cnoring-rxjs-fundamentals": {
             "desc": "A free book that covers all facets of working with Rxjs from your first Observable to how to make your code run at optimal speed with Schedulers.",
             "rev": true,
-            "title": "RxJS 5 Ultimate",
-            "url": "https://www.gitbook.com/book/chrisnoring/rxjs-5-ultimate/details"
+            "title": "RxJS Ultimate",
+            "url": "https://chrisnoring.gitbooks.io/rxjs-5-ultimate/content/"
           },
           "vsavkin-angular-router": {
             "desc": "This book is a comprehensive guide to the Angular router written by its designer. The book explores the library in depth, including the mental model, design constraints, subtleties of the API.",
@@ -642,18 +553,6 @@
             "title": "Academia Binaria (español)",
             "url": "http://academia-binaria.com/"
           },
-          "-KLIzIOgdPXzI4LMOzYP": {
-            "desc": "In this course, you will learn the features listed above and so much more. This amazing Angular tutorial will cover the fundamentals of Angular (you don’t even need to know Angular), TypeScript, and introduction to the programming concepts such as conditions, arrays, functions, directives, pipes, etc.",
-            "rev": true,
-            "title": "Eduonix Angular Fundamentals",
-            "url": "https://www.eduonix.com/courses/Web-Development/angular-2-fundamentals-for-web-developers"
-          },
-          "-KMUuOWwciL_S_o0fzFO": {
-            "desc": "The ngMigrate project is brought to you by Todd Motto, a Developer Advocate at Telerik, spreading the good word of Kendo UI, NativeScript and Angular & AngularJS. You can follow him on Twitter for questions, or even requests about this guide.",
-            "rev": true,
-            "title": "ngMigrate",
-            "url": "http://ngmigrate.telerik.com/"
-          },
           "-KN3uNQvxifu26D6WKJW": {
             "category": "Education",
             "desc": "Create the future of web applications by taking Angular for a test drive.",
@@ -674,14 +573,14 @@
             "logo": "",
             "rev": true,
             "title": "Pluralsight",
-            "url": "https://www.pluralsight.com/search?q=angular+2&categories=all"
+            "url": "https://www.pluralsight.com/paths/angular"
           },
           "ab3": {
             "desc": "Angular courses hosted by  Udemy",
             "logo": "",
             "rev": true,
             "title": "Udemy",
-            "url": "https://www.udemy.com/courses/search/?ref=home&src=ukw&q=angular+2&lang=en"
+            "url": "https://www.udemy.com/courses/search/?q=angular"
           },
           "ab4": {
             "desc": "Angular Fundamentals and advanced topics focused on Redux Style Angular Applications",
@@ -695,13 +594,7 @@
             "logo": "",
             "rev": true,
             "title": "Frontend Masters",
-            "url": "https://frontendmasters.com/courses/angular-2/"
-          },
-          "ac6": {
-            "desc": "French language Angular course covering TypeScript, ES6, Dependency Injection, Observables, and more.",
-            "rev": true,
-            "title": "Wishtack's Angular Course (francais)",
-            "url": "http://courses.wishtack.com/angular-2/ecmascript-6"
+            "url": "https://frontendmasters.com/courses/angular-core/"
           },
           "angular-love": {
             "desc": "Polish language Angular articles and information",
@@ -709,12 +602,6 @@
             "title": "angular.love (Polski)",
             "url": "http://www.angular.love/"
           },
-          "angular2forms": {
-            "desc": "Learn about how to use Reactive Forms with Angular.",
-            "rev": true,
-            "title": "Angular Forms: Data Binding and Validation",
-            "url": "https://www.lynda.com/AngularJS-tutorials/Angular-2-Forms-Data-Binding-Validation/461451-2.html"
-          },
           "learn-angular-fr": {
             "desc": "French language Angular content.",
             "rev": true,
@@ -790,7 +677,7 @@
             "desc": "Basic and Advanced training across Europe in German",
             "rev": true,
             "title": "TheCodeCampus (German)",
-            "url": "https://www.thecodecampus.de/#!/angularjs"
+            "url": "https://www.thecodecampus.de/schulungen/angular"
           },
           "-KLIzFhfGKi1xttqJ7Uh": {
             "desc": "4 day in-depth Angular training in Israel",
@@ -823,13 +710,6 @@
             "title": "Angular Boot Camp",
             "url": "https://angularbootcamp.com"
           },
-          "ab": {
-            "desc": "With Rangle’s Custom Training, you can cover Angular in comprehensive detail, on your premises or theirs. Learn directly from Angular experts who will tailor course material to suit your specific application needs.",
-            "logo": "",
-            "rev": true,
-            "title": "Rangle.io",
-            "url": "http://rangle.io/services/javascript-training/angular2-training/"
-          },
           "ab3": {
             "desc": "Trainings & Code Reviews. We help people to get a deep understanding of different technologies through trainings and code reviews. Our services can be arranged online, making it possible to join in from anywhere in the world, or on-site to get the best experience possible.",
             "logo": "",
@@ -844,12 +724,6 @@
             "title": "Learn Javascript (Russian)",
             "url": "https://learn.javascript.ru/courses/angular"
           },
-          "sa200": {
-            "desc": "Free Angular training delivered by SFEIR in France",
-            "rev": true,
-            "title": "SFEIR School (French)",
-            "url": "https://school.sfeir.com/project/sa200/"
-          },
           "zenika-angular": {
             "desc": "Angular trainings delivered by Zenika (FRANCE)",
             "rev": true,

aio/content/navigation.json

@@ -208,16 +208,16 @@
               "title": "Component Styles",
               "tooltip": "Add CSS styles that are specific to a component."
             },
-            {
-              "url": "guide/elements",
-              "title": "Angular Elements",
-              "tooltip": "Convert components to Custom Elements."
-            },
             {
               "url": "guide/dynamic-component-loader",
               "title": "Dynamic Components",
               "tooltip": "Load components dynamically."
             },
+            {
+              "url": "guide/elements",
+              "title": "Angular Elements",
+              "tooltip": "Convert components to Custom Elements."
+            },
             {
               "url": "guide/attribute-directives",
               "title": "Attribute Directives",
@@ -456,6 +456,11 @@
           "title": "Internationalization (i18n)",
           "tooltip": "Translate the app's template text into multiple languages."
         },
+        {
+          "url": "guide/accessibility",
+          "title": "Accessibility",
+          "tooltip": "Design apps to be accessible to all users."
+        },
         {
           "title": "Service Workers & PWA",
           "tooltip": "Angular service workers: Controlling caching of application resources.",

aio/content/start/index.md

@@ -42,7 +42,7 @@ We've seeded this particular app with a top bar—containing the store name
 <div class="callout is-helpful">
 <header>StackBlitz tips</header>
 
-* Log into StackBlitz, so you can save and resume your work. If you have a GitHub account, you can log into StackBlitz with that account. 
+* Log into StackBlitz, so you can save and resume your work. If you have a GitHub account, you can log into StackBlitz with that account. In order to save your progress, first fork the project using the Fork button at the top left, then you'll be able to save your work to your own StackBlitz account by clicking the Save button.
 * To copy a code example from this tutorial, click the icon at the top right of the code example box, and then paste the code snippet from the clipboard into StackBlitz. 
 * If the StackBlitz preview pane isn't showing what you expect, save and then click the refresh button. 
 * StackBlitz is continually improving, so there may be slight differences in generated code, but the app's behavior will be the same.

aio/content/tutorial/toh-pt1.md

@@ -13,13 +13,11 @@ Using the Angular CLI, generate a new component named `heroes`.
 </code-example>
 
 The CLI creates a new folder, `src/app/heroes/`, and generates
-the four files of the  `HeroesComponent`.
+the three files of the  `HeroesComponent` along with a test file.
 
 The `HeroesComponent` class file is as follows:
 
-<code-example 
-  path="toh-pt1/src/app/heroes/heroes.component.ts" region="v1" 
-  header="app/heroes/heroes.component.ts (initial version)" linenums="false">
+<code-example path="toh-pt1/src/app/heroes/heroes.component.ts" region="v1" header="app/heroes/heroes.component.ts (initial version)" linenums="false">
 </code-example>
 
 You always import the `Component` symbol from the Angular core library
@@ -38,13 +36,13 @@ The CLI generated three metadata properties:
 The [CSS element selector](https://developer.mozilla.org/en-US/docs/Web/CSS/Type_selectors),
 `'app-heroes'`, matches the name of the HTML element that identifies this component within a parent component's template.
 
-The `ngOnInit` is a [lifecycle hook](guide/lifecycle-hooks#oninit). 
-Angular calls `ngOnInit` shortly after creating a component.
+The `ngOnInit()` is a [lifecycle hook](guide/lifecycle-hooks#oninit).
+Angular calls `ngOnInit()` shortly after creating a component.
 It's a good place to put initialization logic.
 
 Always `export` the component class so you can `import` it elsewhere ... like in the `AppModule`.
 
-### Add a _hero_ property
+### Add a `hero` property
 
 Add a `hero` property to the `HeroesComponent` for a hero named "Windstorm."
 
@@ -54,17 +52,17 @@ Add a `hero` property to the `HeroesComponent` for a hero named "Windstorm."
 ### Show the hero
 
 Open the `heroes.component.html` template file.
-Delete the default text generated by the Angular CLI and 
-replace it with a data binding to the new `hero` property.  
+Delete the default text generated by the Angular CLI and
+replace it with a data binding to the new `hero` property.
 
 <code-example path="toh-pt1/src/app/heroes/heroes.component.1.html" header="heroes.component.html" region="show-hero-1" linenums="false">
 </code-example>
 
-## Show the _HeroesComponent_ view
+## Show the `HeroesComponent` view
 
 To display the `HeroesComponent`, you must add it to the template of the shell `AppComponent`.
 
-Remember that `app-heroes` is the [element selector](#selector) for the `HeroesComponent`. 
+Remember that `app-heroes` is the [element selector](#selector) for the `HeroesComponent`.
 So add an `<app-heroes>` element to the `AppComponent` template file, just below the title.
 
 <code-example path="toh-pt1/src/app/app.component.html" header="src/app/app.component.html" linenums="false">
@@ -102,10 +100,7 @@ The page no longer displays properly because you changed the hero from a string
 Update the binding in the template to announce the hero's name
 and show both `id` and `name` in a details layout like this:
 
-<code-example 
-  path="toh-pt1/src/app/heroes/heroes.component.1.html"
-  region="show-hero-2" 
-  header="heroes.component.html (HeroesComponent's template)" linenums="false">
+<code-example path="toh-pt1/src/app/heroes/heroes.component.1.html" region="show-hero-2" header="heroes.component.html (HeroesComponent's template)" linenums="false">
 </code-example>
 
 The browser refreshes and displays the hero's information.
@@ -113,14 +108,12 @@ The browser refreshes and displays the hero's information.
 ## Format with the _UppercasePipe_
 
 Modify the `hero.name` binding like this.
-<code-example
-  path="toh-pt1/src/app/heroes/heroes.component.html"
-  region="pipe">
+<code-example path="toh-pt1/src/app/heroes/heroes.component.html" header="src/app/heroes/heroes.component.html" region="pipe">
 </code-example>
 
 The browser refreshes and now the hero's name is displayed in capital letters.
 
-The word `uppercase` in the interpolation binding, 
+The word `uppercase` in the interpolation binding,
 right after the pipe operator ( | ),
 activates the built-in `UppercasePipe`.
 
@@ -133,7 +126,7 @@ Users should be able to edit the hero name in an `<input>` textbox.
 
 The textbox should both _display_ the hero's `name` property
 and _update_ that property as the user types.
-That means data flow from the component class _out to the screen_ and
+That means data flows from the component class _out to the screen_ and
 from the screen _back to the class_.
 
 To automate that data flow, setup a two-way data binding between the `<input>` form element and the `hero.name` property.
@@ -146,7 +139,7 @@ Refactor the details area in the `HeroesComponent` template so it looks like thi
 
 </code-example>
 
-**[(ngModel)]** is Angular's two-way data binding syntax. 
+**[(ngModel)]** is Angular's two-way data binding syntax.
 
 Here it binds the `hero.name` property to the HTML textbox so that data can flow _in both directions:_ from the `hero.name` property to the textbox, and from the textbox back to the `hero.name`.
 
@@ -162,7 +155,7 @@ Template parse errors:
 Can't bind to 'ngModel' since it isn't a known property of 'input'.
 </code-example>
 
-Although `ngModel` is a valid Angular directive, it isn't available by default. 
+Although `ngModel` is a valid Angular directive, it isn't available by default.
 
 It belongs to the optional `FormsModule` and you must _opt-in_ to using it.
 
@@ -170,7 +163,7 @@ It belongs to the optional `FormsModule` and you must _opt-in_ to using it.
 
 Angular needs to know how the pieces of your application fit together
 and what other files and libraries the app requires.
-This information is called _metadata_
+This information is called _metadata_.
 
 Some of the metadata is in the `@Component` decorators that you added to your component classes.
 Other critical metadata is in [`@NgModule`](guide/ngmodules) decorators.
@@ -182,7 +175,7 @@ This is where you _opt-in_ to the `FormsModule`.
 
 ### Import _FormsModule_
 
-Open `AppModule` (`app.module.ts`) and import the `FormsModule` symbol from the `@angular/forms` library. 
+Open `AppModule` (`app.module.ts`) and import the `FormsModule` symbol from the `@angular/forms` library.
 
 <code-example path="toh-pt1/src/app/app.module.ts" header="app.module.ts (FormsModule symbol import)"
  region="formsmodule-js-import">
@@ -190,13 +183,13 @@ Open `AppModule` (`app.module.ts`) and import the `FormsModule` symbol from the
 
 Then add `FormsModule` to the `@NgModule` metadata's `imports` array, which contains a list of external modules that the app needs.
 
-<code-example path="toh-pt1/src/app/app.module.ts" header="app.module.ts ( @NgModule imports)"
+<code-example path="toh-pt1/src/app/app.module.ts" header="app.module.ts (@NgModule imports)"
 region="ng-imports">
 </code-example>
 
 When the browser refreshes, the app should work again. You can edit the hero's name and see the changes reflected immediately in the `<h2>` above the textbox.
 
-### Declare _HeroesComponent_ 
+### Declare `HeroesComponent`
 
 Every component must be declared in _exactly one_ [NgModule](guide/ngmodules).
 
@@ -206,11 +199,11 @@ So why did the application work?
 It worked because the Angular CLI declared `HeroesComponent` in the `AppModule` when it generated that component.
 
 Open `src/app/app.module.ts` and find `HeroesComponent` imported near the top.
-<code-example path="toh-pt1/src/app/app.module.ts" region="heroes-import" >
+<code-example path="toh-pt1/src/app/app.module.ts" header="src/app/app.module.ts" region="heroes-import" >
 </code-example>
 
 The `HeroesComponent` is declared in the `@NgModule.declarations` array.
-<code-example path="toh-pt1/src/app/app.module.ts" region="declarations">
+<code-example path="toh-pt1/src/app/app.module.ts" header="src/app/app.module.ts" region="declarations">
 </code-example>
 
 Note that `AppModule`  declares both application components, `AppComponent` and `HeroesComponent`.
@@ -228,7 +221,7 @@ Your app should look like this <live-example></live-example>. Here are the code
   <code-pane header="src/app/heroes/heroes.component.html" path="toh-pt1/src/app/heroes/heroes.component.html">
   </code-pane>
 
-  <code-pane header="src/app/app.module.ts" 
+  <code-pane header="src/app/app.module.ts"
   path="toh-pt1/src/app/app.module.ts">
   </code-pane>
 
@@ -238,7 +231,7 @@ Your app should look like this <live-example></live-example>. Here are the code
   <code-pane header="src/app/app.component.html" path="toh-pt1/src/app/app.component.html">
   </code-pane>
 
-  <code-pane header="src/app/hero.ts" 
+  <code-pane header="src/app/hero.ts"
   path="toh-pt1/src/app/hero.ts">
   </code-pane>
 
@@ -247,10 +240,10 @@ Your app should look like this <live-example></live-example>. Here are the code
 ## Summary
 
 * You used the CLI to create a second `HeroesComponent`.
-* You displayed the `HeroesComponent` by adding it to the `AppComponent` shell. 
+* You displayed the `HeroesComponent` by adding it to the `AppComponent` shell.
 * You applied the `UppercasePipe` to format the name.
 * You used two-way data binding with the `ngModel` directive.
 * You learned about the `AppModule`.
-* You imported the `FormsModule` in the `AppModule` so that Angular would recognize and apply the `ngModel` directive. 
+* You imported the `FormsModule` in the `AppModule` so that Angular would recognize and apply the `ngModel` directive.
 * You learned the importance of declaring components in the `AppModule`
 and appreciated that the CLI declared it for you.

aio/content/tutorial/toh-pt2.md

@@ -21,19 +21,17 @@ header="src/app/mock-heroes.ts">
 
 ## Displaying heroes
 
-You're about to display the list of heroes at the top of the `HeroesComponent`.
-
 Open the `HeroesComponent` class file and import the mock `HEROES`.
 
 <code-example path="toh-pt2/src/app/heroes/heroes.component.ts" region="import-heroes" header="src/app/heroes/heroes.component.ts (import HEROES)">
 </code-example>
 
-In the same file (`HeroesComponent` class), define a component property called `heroes` to expose `HEROES` array for binding.
+In the same file (`HeroesComponent` class), define a component property called `heroes` to expose the `HEROES` array for binding.
 
-<code-example path="toh-pt2/src/app/heroes/heroes.component.ts" region="component">
+<code-example path="toh-pt2/src/app/heroes/heroes.component.ts" header="src/app/heroes/heroes.component.ts" region="component">
 </code-example>
 
-### List heroes with _*ngFor_
+### List heroes with `*ngFor`
 
 Open the `HeroesComponent` template file and make the following changes:
 
@@ -47,7 +45,7 @@ Make it look like this:
 <code-example path="toh-pt2/src/app/heroes/heroes.component.1.html" region="list" header="heroes.component.html (heroes template)" linenums="false">
 </code-example>
 
-Now change the `<li>` to this:
+That shows one hero. To list them all, add an `*ngFor` to the `<li>` to iterate through the list of heroes:
 
 <code-example path="toh-pt2/src/app/heroes/heroes.component.1.html" region="li">
 </code-example>
@@ -55,10 +53,10 @@ Now change the `<li>` to this:
 The [`*ngFor`](guide/template-syntax#ngFor) is Angular's _repeater_ directive.
 It repeats the host element for each element in a list.
 
-In this example
+The syntax in this example is as follows:
 
-* `<li>` is the host element
-* `heroes` is the list from the `HeroesComponent` class.
+* `<li>` is the host element.
+* `heroes` holds the mock heroes list from the `HeroesComponent` class, the mock heroes list.
 * `hero` holds the current hero object for each iteration through the list.
 
 <div class="alert is-important">
@@ -127,9 +125,10 @@ This is an example of Angular's [event binding](guide/template-syntax#event-bind
 The parentheses around `click` tell Angular to listen for the `<li>` element's  `click` event.
 When the user clicks in the `<li>`, Angular executes the `onSelect(hero)` expression.
 
-`onSelect()` is a `HeroesComponent` method that you're about to write.
-Angular calls it with the `hero` object displayed in the clicked `<li>`,
-the same `hero` defined previously in the `*ngFor` expression.
+
+In the next section, define an `onSelect()` method in `HeroesComponent` to
+display the hero that was defined in the `*ngFor` expression.
+
 
 ### Add the click event handler
 
@@ -142,10 +141,11 @@ to the component's `selectedHero`.
 <code-example path="toh-pt2/src/app/heroes/heroes.component.ts" region="on-select" header="src/app/heroes/heroes.component.ts (onSelect)" linenums="false">
 </code-example>
 
-### Update the details template
+### Add a details section
 
-The template still refers to the component's old `hero` property which no longer exists.
-Rename `hero` to `selectedHero`.
+Currently, you have a list in the component template. To click on a hero on the list
+and reveal details about that hero, you need a section for the details to render in the
+template. Add the following to `heroes.component.html` beneath the list section:
 
 <code-example path="toh-pt2/src/app/heroes/heroes.component.html" region="selectedHero-details" header="heroes.component.html (selected hero details)" linenums="false">
 </code-example>
@@ -162,7 +162,7 @@ Open the browser developer tools and look in the console for an error message li
 
 When the app starts, the `selectedHero` is `undefined` _by design_.
 
-Binding expressions in the template that refer to properties of `selectedHero` &mdash; expressions like `{{selectedHero.name}}` &mdash; _must fail_ because there is no selected hero.
+Binding expressions in the template that refer to properties of `selectedHero`&mdash;expressions like `{{selectedHero.name}}`&mdash;_must fail_ because there is no selected hero.
 
 
 #### The fix - hide empty details with _*ngIf_
@@ -192,7 +192,7 @@ The heroes appear in a list and details about the clicked hero appear at the bot
 
 #### Why it works
 
-When `selectedHero` is undefined, the `ngIf` removes the hero detail from the DOM. There are no `selectedHero` bindings to worry about.
+When `selectedHero` is undefined, the `ngIf` removes the hero detail from the DOM. There are no `selectedHero` bindings to consider.
 
 When the user picks a hero, `selectedHero` has a value and
 `ngIf` puts the hero detail into the DOM.
@@ -240,7 +240,7 @@ Here are the code files discussed on this page, including the `HeroesComponent`
 
   <code-pane header="src/app/mock-heroes.ts" path="toh-pt2/src/app/mock-heroes.ts">
   </code-pane>
-  
+
   <code-pane header="src/app/heroes/heroes.component.ts" path="toh-pt2/src/app/heroes/heroes.component.ts">
   </code-pane>
 

aio/content/tutorial/toh-pt3.md

@@ -72,7 +72,7 @@ Amend the `@angular/core` import statement to include the `Input` symbol.
 
 Add a `hero` property, preceded by the `@Input()` decorator.
 
-<code-example path="toh-pt3/src/app/hero-detail/hero-detail.component.ts" region="input-hero"  linenums="false">
+<code-example path="toh-pt3/src/app/hero-detail/hero-detail.component.ts" header="src/app/hero-detail/hero-detail.component.ts" region="input-hero"  linenums="false">
 </code-example>
 
 That's the only change you should make to the `HeroDetailComponent` class.

aio/content/tutorial/toh-pt4.md

@@ -11,18 +11,18 @@ Components shouldn't fetch or save data directly and they certainly shouldn't kn
 They should focus on presenting data and delegate data access to a service.
 
 In this tutorial, you'll create a `HeroService` that all application classes can use to get heroes.
-Instead of creating that service with `new`, 
-you'll rely on Angular [*dependency injection*](guide/dependency-injection) 
+Instead of creating that service with `new`,
+you'll rely on Angular [*dependency injection*](guide/dependency-injection)
 to inject it into the `HeroesComponent` constructor.
 
 Services are a great way to share information among classes that _don't know each other_.
 You'll create a `MessageService` and inject it in two places:
 
-1. in `HeroService` which uses the service to send a message.
-2. in `MessagesComponent` which displays that message.
+1. in `HeroService` which uses the service to send a message
+2. in `MessagesComponent` which displays that message
 
 
-## Create the _HeroService_
+## Create the `HeroService`
 
 Using the Angular CLI, create a service called `hero`.
 
@@ -30,24 +30,24 @@ Using the Angular CLI, create a service called `hero`.
   ng generate service hero
 </code-example>
 
-The command generates skeleton `HeroService` class in `src/app/hero.service.ts`
-The `HeroService` class should look like the following example.
+The command generates a skeleton `HeroService` class in `src/app/hero.service.ts` as follows:
 
 <code-example path="toh-pt4/src/app/hero.service.1.ts" region="new"
  header="src/app/hero.service.ts (new service)" linenums="false">
 </code-example>
 
-### _@Injectable()_ services
+
+### `@Injectable()` services
 
 Notice that the new service imports the Angular `Injectable` symbol and annotates
 the class with the `@Injectable()` decorator. This marks the class as one that participates in the _dependency injection system_. The `HeroService` class is going to provide an injectable service, and it can also have its own injected dependencies.
 It doesn't have any dependencies yet, but [it will soon](#inject-message-service).
 
-The `@Injectable()` decorator accepts a metadata object for the service, the same way the `@Component()` decorator did for your component classes. 
+The `@Injectable()` decorator accepts a metadata object for the service, the same way the `@Component()` decorator did for your component classes.
 
 ### Get hero data
 
-The `HeroService` could get hero data from anywhere&mdash;a web service, local storage, or a mock data source. 
+The `HeroService` could get hero data from anywhere&mdash;a web service, local storage, or a mock data source.
 
 Removing data access from components means you can change your mind about the implementation anytime, without touching any components.
 They don't know how the service works.
@@ -56,27 +56,25 @@ The implementation in _this_ tutorial will continue to deliver _mock heroes_.
 
 Import the `Hero` and `HEROES`.
 
-<code-example path="toh-pt4/src/app/hero.service.ts" region="import-heroes">
+<code-example path="toh-pt4/src/app/hero.service.ts" header="src/app/hero.service.ts" region="import-heroes">
 </code-example>
 
 Add a `getHeroes` method to return the _mock heroes_.
 
-<code-example path="toh-pt4/src/app/hero.service.1.ts" region="getHeroes">
+<code-example path="toh-pt4/src/app/hero.service.1.ts" header="src/app/hero.service.ts" region="getHeroes">
 </code-example>
 
 {@a provide}
 ## Provide the `HeroService`
 
-You must make the `HeroService` available to the dependency injection system 
-before Angular can _inject_ it into the `HeroesComponent`, 
-as you will do [below](#inject). You do this by registering a _provider_. A provider is something that can create or deliver a service; in this case, it instantiates the `HeroService` class to provide the service.
+You must make the `HeroService` available to the dependency injection system
+before Angular can _inject_ it into the `HeroesComponent` by registering a _provider_. A provider is something that can create or deliver a service; in this case, it instantiates the `HeroService` class to provide the service.
 
-Now, you need to make sure that the `HeroService` is registered as the provider of this service. 
-You are registering it with an _injector_, which is the object that is responsible for choosing and injecting the provider where it is required. 
+To make sure that the `HeroService` can provide this service, register it
+with the _injector_, which is the object that is responsible for choosing
+and injecting the provider where the app requires it.
 
-By default, the Angular CLI command `ng generate service` registers a provider with the _root injector_ for your service by including provider metadata in the `@Injectable` decorator. 
-
-If you look at the `@Injectable()` statement right before the `HeroService` class definition, you can see that the `providedIn` metadata value is 'root':    
+By default, the Angular CLI command `ng generate service` registers a provider with the _root injector_ for your service by including provider metadata, that is `providedIn: 'root'` in the `@Injectable()` decorator.
 
 ```
 @Injectable({
@@ -84,8 +82,8 @@ If you look at the `@Injectable()` statement right before the `HeroService` clas
 })
 ```
 
-When you provide the service at the root level, Angular creates a single, shared instance of `HeroService` and injects into any class that asks for it. 
-Registering the provider in the `@Injectable` metadata also allows Angular to optimize an app by removing the service if it turns out not to be used after all. 
+When you provide the service at the root level, Angular creates a single, shared instance of `HeroService` and injects into any class that asks for it.
+Registering the provider in the `@Injectable` metadata also allows Angular to optimize an app by removing the service if it turns out not to be used after all.
 
 <div class="alert is-helpful">
 
@@ -115,7 +113,7 @@ Import the `HeroService` instead.
 
 Replace the definition of the `heroes` property with a simple declaration.
 
-<code-example path="toh-pt4/src/app/heroes/heroes.component.ts" region="heroes">
+<code-example path="toh-pt4/src/app/heroes/heroes.component.ts" header="src/app/heroes/heroes.component.ts" region="heroes">
 </code-example>
 
 {@a inject}
@@ -124,24 +122,24 @@ Replace the definition of the `heroes` property with a simple declaration.
 
 Add a private `heroService` parameter of type `HeroService` to the constructor.
 
-<code-example path="toh-pt4/src/app/heroes/heroes.component.ts" region="ctor">
+<code-example path="toh-pt4/src/app/heroes/heroes.component.ts" header="src/app/heroes/heroes.component.ts" region="ctor">
 </code-example>
 
 The parameter simultaneously defines a private `heroService` property and identifies it as a `HeroService` injection site.
 
 When Angular creates a `HeroesComponent`, the [Dependency Injection](guide/dependency-injection) system
-sets the `heroService` parameter to the singleton instance of `HeroService`. 
+sets the `heroService` parameter to the singleton instance of `HeroService`.
 
-### Add _getHeroes()_
+### Add `getHeroes()`
 
 Create a function to retrieve the heroes from the service.
 
-<code-example path="toh-pt4/src/app/heroes/heroes.component.1.ts" region="getHeroes">
+<code-example path="toh-pt4/src/app/heroes/heroes.component.1.ts" header="src/app/heroes/heroes.component.ts" region="getHeroes">
 </code-example>
 
 {@a oninit}
 
-### Call it in `ngOnInit`
+### Call it in `ngOnInit()`
 
 While you could call `getHeroes()` in the constructor, that's not the best practice.
 
@@ -150,29 +148,29 @@ The constructor shouldn't _do anything_.
 It certainly shouldn't call a function that makes HTTP requests to a remote server as a _real_ data service would.
 
 Instead, call `getHeroes()` inside the [*ngOnInit lifecycle hook*](guide/lifecycle-hooks) and
-let Angular call `ngOnInit` at an appropriate time _after_ constructing a `HeroesComponent` instance.
+let Angular call `ngOnInit()` at an appropriate time _after_ constructing a `HeroesComponent` instance.
 
-<code-example path="toh-pt4/src/app/heroes/heroes.component.ts" region="ng-on-init">
+<code-example path="toh-pt4/src/app/heroes/heroes.component.ts" header="src/app/heroes/heroes.component.ts" region="ng-on-init">
 </code-example>
 
 ### See it run
 
-After the browser refreshes, the app should run as before, 
+After the browser refreshes, the app should run as before,
 showing a list of heroes and a hero detail view when you click on a hero name.
 
 ## Observable data
 
 The `HeroService.getHeroes()` method has a _synchronous signature_,
 which implies that the `HeroService` can fetch heroes synchronously.
-The `HeroesComponent` consumes the `getHeroes()` result 
+The `HeroesComponent` consumes the `getHeroes()` result
 as if heroes could be fetched synchronously.
 
-<code-example path="toh-pt4/src/app/heroes/heroes.component.1.ts" region="get-heroes">
+<code-example path="toh-pt4/src/app/heroes/heroes.component.1.ts" header="src/app/heroes/heroes.component.ts" region="get-heroes">
 </code-example>
 
 This will not work in a real app.
 You're getting away with it now because the service currently returns _mock heroes_.
-But soon the app will fetch heroes from a remote server, 
+But soon the app will fetch heroes from a remote server,
 which is an inherently _asynchronous_ operation.
 
 The `HeroService` must wait for the server to respond,
@@ -181,13 +179,11 @@ and the browser will not block while the service waits.
 
 `HeroService.getHeroes()` must have an _asynchronous signature_ of some kind.
 
-It can take a callback. It could return a `Promise`. It could return an `Observable`.
-
 In this tutorial, `HeroService.getHeroes()` will return an `Observable`
-in part because it will eventually use the Angular `HttpClient.get` method to fetch the heroes
+because it will eventually use the Angular `HttpClient.get` method to fetch the heroes
 and [`HttpClient.get()` returns an `Observable`](guide/http).
 
-### Observable _HeroService_
+### Observable `HeroService`
 
 `Observable` is one of the key classes in the [RxJS library](http://reactivex.io/rxjs/).
 
@@ -196,13 +192,12 @@ In this tutorial, you'll simulate getting data from the server with the RxJS `of
 
 Open the `HeroService` file and import the `Observable` and `of` symbols from RxJS.
 
-<code-example path="toh-pt4/src/app/hero.service.ts" 
-header="src/app/hero.service.ts (Observable imports)" region="import-observable">
+<code-example path="toh-pt4/src/app/hero.service.ts" header="src/app/hero.service.ts (Observable imports)" region="import-observable">
 </code-example>
 
-Replace the `getHeroes` method with this one.
+Replace the `getHeroes()` method with the following:
 
-<code-example path="toh-pt4/src/app/hero.service.ts" region="getHeroes-1"></code-example>
+<code-example path="toh-pt4/src/app/hero.service.ts" header="src/app/hero.service.ts" region="getHeroes-1"></code-example>
 
 `of(HEROES)` returns an `Observable<Hero[]>` that emits  _a single value_, the array of mock heroes.
 
@@ -212,7 +207,7 @@ In the [HTTP tutorial](tutorial/toh-pt6), you'll call `HttpClient.get<Hero[]>()`
 
 </div>
 
-### Subscribe in _HeroesComponent_
+### Subscribe in `HeroesComponent`
 
 The `HeroService.getHeroes` method used to return a `Hero[]`.
 Now it returns an `Observable<Hero[]>`.
@@ -224,11 +219,11 @@ Find the `getHeroes` method and replace it with the following code
 
 <code-tabs>
 
-  <code-pane header="heroes.component.ts (Observable)" 
+  <code-pane header="heroes.component.ts (Observable)"
     path="toh-pt4/src/app/heroes/heroes.component.ts" region="getHeroes">
   </code-pane>
 
-  <code-pane header="heroes.component.ts (Original)" 
+  <code-pane header="heroes.component.ts (Original)"
     path="toh-pt4/src/app/heroes/heroes.component.1.ts" region="getHeroes">
   </code-pane>
 
@@ -242,9 +237,9 @@ or the browser could freeze the UI while it waited for the server's response.
 
 That _won't work_ when the `HeroService` is actually making requests of a remote server.
 
-The new version waits for the `Observable` to emit the array of heroes&mdash; 
-which could happen now or several minutes from now.
-Then `subscribe` passes the emitted array to the callback,
+The new version waits for the `Observable` to emit the array of heroes&mdash;which
+could happen now or several minutes from now.
+The `subscribe()` method passes the emitted array to the callback,
 which sets the component's `heroes` property.
 
 This asynchronous approach _will work_ when
@@ -252,14 +247,14 @@ the `HeroService` requests heroes from the server.
 
 ## Show messages
 
-In this section you will 
+This section guides you through the following:
 
-* add a `MessagesComponent` that displays app messages at the bottom of the screen.
-* create an injectable, app-wide `MessageService` for sending messages to be displayed
-* inject `MessageService` into the `HeroService`
-* display a message when `HeroService` fetches heroes successfully.
+* adding a `MessagesComponent` that displays app messages at the bottom of the screen
+* creating an injectable, app-wide `MessageService` for sending messages to be displayed
+* injecting `MessageService` into the `HeroService`
+* displaying a message when `HeroService` fetches heroes successfully
 
-### Create _MessagesComponent_
+### Create `MessagesComponent`
 
 Use the CLI to create the `MessagesComponent`.
 
@@ -269,18 +264,18 @@ Use the CLI to create the `MessagesComponent`.
 
 The CLI creates the component files in the `src/app/messages` folder and declares the `MessagesComponent` in `AppModule`.
 
-Modify the `AppComponent` template to display the generated `MessagesComponent`
+Modify the `AppComponent` template to display the generated `MessagesComponent`.
 
 <code-example
-  header = "/src/app/app.component.html"
+  header = "src/app/app.component.html"
   path="toh-pt4/src/app/app.component.html">
 </code-example>
 
 You should see the default paragraph from `MessagesComponent` at the bottom of the page.
 
-### Create the _MessageService_
+### Create the `MessageService`
 
-Use the CLI to create the `MessageService` in `src/app`. 
+Use the CLI to create the `MessageService` in `src/app`.
 
 <code-example language="sh" class="code-shell">
   ng generate service message
@@ -288,9 +283,7 @@ Use the CLI to create the `MessageService` in `src/app`.
 
 Open `MessageService` and replace its contents with the following.
 
-<code-example
-  header = "/src/app/message.service.ts"
-  path="toh-pt4/src/app/message.service.ts">
+<code-example header = "src/app/message.service.ts" path="toh-pt4/src/app/message.service.ts">
 </code-example>
 
 The service exposes its cache of `messages` and two methods: one to `add()` a message to the cache and another to `clear()` the cache.
@@ -298,19 +291,19 @@ The service exposes its cache of `messages` and two methods: one to `add()` a me
 {@a inject-message-service}
 ### Inject it into the `HeroService`
 
-Re-open the `HeroService` and import the `MessageService`.
+In `HeroService`, import the `MessageService`.
 
 <code-example
-  header = "/src/app/hero.service.ts (import MessageService)"
+  header = "src/app/hero.service.ts (import MessageService)"
   path="toh-pt4/src/app/hero.service.ts" region="import-message-service">
 </code-example>
 
 Modify the constructor with a parameter that declares a private `messageService` property.
-Angular will inject the singleton `MessageService` into that property 
+Angular will inject the singleton `MessageService` into that property
 when it creates the `HeroService`.
 
 <code-example
-  path="toh-pt4/src/app/hero.service.ts" region="ctor">
+  path="toh-pt4/src/app/hero.service.ts" header="src/app/hero.service.ts" region="ctor">
 </code-example>
 
 <div class="alert is-helpful">
@@ -322,32 +315,29 @@ you inject the `MessageService` into the `HeroService` which is injected into th
 
 ### Send a message from `HeroService`
 
-Modify the `getHeroes` method to send a message when the heroes are fetched.
+Modify the `getHeroes()` method to send a message when the heroes are fetched.
 
-<code-example path="toh-pt4/src/app/hero.service.ts" region="getHeroes">
+<code-example path="toh-pt4/src/app/hero.service.ts" header="src/app/hero.service.ts" region="getHeroes">
 </code-example>
 
 ### Display the message from `HeroService`
 
-The `MessagesComponent` should display all messages, 
+The `MessagesComponent` should display all messages,
 including the message sent by the `HeroService` when it fetches heroes.
 
 Open `MessagesComponent` and import the `MessageService`.
 
-<code-example
-  header = "/src/app/messages/messages.component.ts (import MessageService)"
-  path="toh-pt4/src/app/messages/messages.component.ts" region="import-message-service">
+<code-example header="src/app/messages/messages.component.ts (import MessageService)" path="toh-pt4/src/app/messages/messages.component.ts" region="import-message-service">
 </code-example>
 
 Modify the constructor with a parameter that declares a **public** `messageService` property.
-Angular will inject the singleton `MessageService` into that property 
+Angular will inject the singleton `MessageService` into that property
 when it creates the `MessagesComponent`.
 
-<code-example
-  path="toh-pt4/src/app/messages/messages.component.ts" region="ctor">
+<code-example path="toh-pt4/src/app/messages/messages.component.ts" header="src/app/messages/messages.component.ts" region="ctor">
 </code-example>
 
-The `messageService` property **must be public** because you're about to bind to it in the template.
+The `messageService` property **must be public** because you're going to bind to it in the template.
 
 <div class="alert is-important">
 
@@ -355,7 +345,7 @@ Angular only binds to _public_ component properties.
 
 </div>
 
-### Bind to the _MessageService_
+### Bind to the `MessageService`
 
 Replace the CLI-generated `MessagesComponent` template with the following.
 
@@ -390,11 +380,11 @@ Here are the code files discussed on this page and your app should look like thi
 
 <code-tabs>
 
-  <code-pane header="src/app/hero.service.ts" 
+  <code-pane header="src/app/hero.service.ts"
   path="toh-pt4/src/app/hero.service.ts">
   </code-pane>
 
-  <code-pane header="src/app/message.service.ts" 
+  <code-pane header="src/app/message.service.ts"
   path="toh-pt4/src/app/message.service.ts">
   </code-pane>
 

aio/content/tutorial/toh-pt5.md

@@ -36,79 +36,74 @@ Use the CLI to generate it.
 
 The generated file looks like this:
 
-<code-example path="toh-pt5/src/app/app-routing.module.0.ts" 
-  header="src/app/app-routing.module.ts (generated)">
+<code-example path="toh-pt5/src/app/app-routing.module.0.ts" header="src/app/app-routing.module.ts (generated)">
 </code-example>
 
-You generally don't declare components in a routing module so you can delete the
-`@NgModule.declarations` array and delete `CommonModule` references too.
+Replace it with the following:
 
-You'll configure the router with `Routes` in the `RouterModule`
-so import those two symbols from the `@angular/router` library.
-
-Add an `@NgModule.exports` array with `RouterModule` in it.
-Exporting `RouterModule` makes router directives available for use
-in the `AppModule` components that will need them.
-
-`AppRoutingModule` looks like this now:
-
-<code-example path="toh-pt5/src/app/app-routing.module.ts" 
-  region="v1"
-  header="src/app/app-routing.module.ts (v1)">
+<code-example path="toh-pt5/src/app/app-routing.module.1.ts" header="src/app/app-routing.module.ts (updated)">
 </code-example>
 
-### Add routes
+First, `AppRoutingModule` imports `RouterModule` and `Routes` so the app can have routing functionality. The next import, `HeroesComponent`, will give the Router somewhere to go once you  configure the routes.
 
-*Routes* tell the router which view to display when a user clicks a link or
+Notice that the `CommonModule` references and `declarations` array are unecessary, so are no
+longer part of `AppRoutingModule`. The following sections explain the rest of the `AppRoutingModule` in more detail.
+
+
+### Routes
+
+The next part of the file is where you configure your routes.
+*Routes* tell the Router which view to display when a user clicks a link or
 pastes a URL into the browser address bar.
 
-A typical Angular `Route` has two properties:
+Since `AppRoutingModule` already imports `HeroesComponent`, you can use it in the `routes` array:
 
-1. `path`: a string that matches the URL in the browser address bar.
-1. `component`: the component that the router should create when navigating to this route.
-
-You intend to navigate to the `HeroesComponent` when the URL is something like `localhost:4200/heroes`.
-
-Import the `HeroesComponent` so you can reference it in a `Route`.
-Then define an array of routes with a single `route` to that component.
-
-<code-example path="toh-pt5/src/app/app-routing.module.ts" 
+<code-example path="toh-pt5/src/app/app-routing.module.ts" header="src/app/app-routing.module.ts"
   region="heroes-route">
 </code-example>
 
-Once you've finished setting up, the router will match that URL to `path: 'heroes'` 
-and display the `HeroesComponent`.
+A typical Angular `Route` has two properties:
 
-### _RouterModule.forRoot()_
+* `path`: a string that matches the URL in the browser address bar.
+* `component`: the component that the router should create when navigating to this route.
 
-You first must initialize the router and start it listening for browser location changes.
+This tells the router to match that URL to `path: 'heroes'`
+and display the `HeroesComponent` when the URL is something like `localhost:4200/heroes`.
 
-Add `RouterModule` to the `@NgModule.imports` array and 
-configure it with the `routes` in one step by calling 
-`RouterModule.forRoot()` _within_ the `imports` array, like this:
+### `RouterModule.forRoot()`
 
-<code-example path="toh-pt5/src/app/app-routing.module.ts" 
-  region="ngmodule-imports">
+The `@NgModule` metadata initializes the router and starts it listening for browser location changes.
+
+The following line adds the `RouterModule` to the `AppRoutingModule` `imports` array and
+configures it with the `routes` in one step by calling
+`RouterModule.forRoot()`:
+
+<code-example path="toh-pt5/src/app/app-routing.module.ts" header="src/app/app-routing.module.ts" region="ngmodule-imports">
 </code-example>
 
 <div class="alert is-helpful">
 
   The method is called `forRoot()` because you configure the router at the application's root level.
-  The `forRoot()` method supplies the service providers and directives needed for routing, 
+  The `forRoot()` method supplies the service providers and directives needed for routing,
   and performs the initial navigation based on the current browser URL.
 
 </div>
 
-## Add _RouterOutlet_
+Next, `AppRoutingModule` exports `RouterModule` so it will be available throughout the app.
 
 Open the `AppComponent` template and replace the `<app-heroes>` element with a `<router-outlet>` element.
 
-<code-example path="toh-pt5/src/app/app.component.html" 
-  region="outlet"
-  header="src/app/app.component.html (router-outlet)">
+<code-example path="toh-pt5/src/app/app-routing.module.ts" header="src/app/app-routing.module.ts (exports array)" region="export-routermodule">
 </code-example>
 
-You removed `<app-heroes>` because you will only display the `HeroesComponent` when the user navigates to it.
+## Add `RouterOutlet`
+
+Open the `AppComponent` template and replace the `<app-heroes>` element with a `<router-outlet>` element.
+
+<code-example path="toh-pt5/src/app/app.component.html" region="outlet" header="src/app/app.component.html (router-outlet)">
+</code-example>
+
+The `AppComponent` template no longer needs `<app-heroes>` because the app will only display the `HeroesComponent` when the user navigates to it.
 
 The `<router-outlet>` tells the router where to display routed views.
 
@@ -129,7 +124,7 @@ You should still be running with this CLI command.
 
 The browser should refresh and display the app title but not the list of heroes.
 
-Look at the browser's address bar. 
+Look at the browser's address bar.
 The URL ends in `/`.
 The route path to `HeroesComponent` is `/heroes`.
 
@@ -140,29 +135,26 @@ You should see the familiar heroes master/detail view.
 
 ## Add a navigation link (`routerLink`)
 
-Users shouldn't have to paste a route URL into the address bar. 
-They should be able to click a link to navigate.
+Ideally, users should be able to click a link to navigate rather
+than pasting a route URL into the address bar.
 
-Add a `<nav>` element and, within that, an anchor element that, when clicked, 
+Add a `<nav>` element and, within that, an anchor element that, when clicked,
 triggers navigation to the `HeroesComponent`.
 The revised `AppComponent` template looks like this:
 
-<code-example 
-  path="toh-pt5/src/app/app.component.html" 
-  region="heroes"
-  header="src/app/app.component.html (heroes RouterLink)">
+<code-example path="toh-pt5/src/app/app.component.html" region="heroes" header="src/app/app.component.html (heroes RouterLink)">
 </code-example>
 
 A [`routerLink` attribute](#routerlink) is set to `"/heroes"`,
 the string that the router matches to the route to `HeroesComponent`.
-The `routerLink` is the selector for the [`RouterLink` directive](#routerlink)
+The `routerLink` is the selector for the [`RouterLink` directive](/api/router/RouterLink)
 that turns user clicks into router navigations.
 It's another of the public directives in the `RouterModule`.
 
-The browser refreshes and displays the app title and heroes link, 
+The browser refreshes and displays the app title and heroes link,
 but not the heroes list.
 
-Click the link. 
+Click the link.
 The address bar updates to `/heroes` and the list of heroes appears.
 
 <div class="alert is-helpful">
@@ -176,7 +168,7 @@ as listed in the [final code review](#appcomponent) below.
 ## Add a dashboard view
 
 Routing makes more sense when there are multiple views.
-So far there's only the heroes view. 
+So far there's only the heroes view.
 
 Add a `DashboardComponent` using the CLI:
 
@@ -186,18 +178,18 @@ Add a `DashboardComponent` using the CLI:
 
 The CLI generates the files for the `DashboardComponent` and declares it in `AppModule`.
 
-Replace the default file content in these three files as follows and then return for a little discussion:
+Replace the default file content in these three files as follows:
 
 <code-tabs>
-  <code-pane 
+  <code-pane
     header="src/app/dashboard/dashboard.component.html" path="toh-pt5/src/app/dashboard/dashboard.component.1.html">
   </code-pane>
 
-  <code-pane 
+  <code-pane
     header="src/app/dashboard/dashboard.component.ts" path="toh-pt5/src/app/dashboard/dashboard.component.ts">
   </code-pane>
 
-  <code-pane 
+  <code-pane
     header="src/app/dashboard/dashboard.component.css" path="toh-pt5/src/app/dashboard/dashboard.component.css">
   </code-pane>
 </code-tabs>
@@ -211,11 +203,11 @@ The  _template_ presents a grid of hero name links.
 The _class_ is similar to the `HeroesComponent` class.
 * It defines a `heroes` array property.
 * The constructor expects Angular to inject the `HeroService` into a private `heroService` property.
-* The `ngOnInit()` lifecycle hook calls `getHeroes`.
+* The `ngOnInit()` lifecycle hook calls `getHeroes()`.
 
-This `getHeroes` returns the sliced list of heroes at positions 1 and 5, returning only four of the Top Heroes (2nd, 3rd, 4th, and 5th).
+This `getHeroes()` returns the sliced list of heroes at positions 1 and 5, returning only four of the Top Heroes (2nd, 3rd, 4th, and 5th).
 
-<code-example path="toh-pt5/src/app/dashboard/dashboard.component.ts" region="getHeroes">
+<code-example path="toh-pt5/src/app/dashboard/dashboard.component.ts" header="src/app/dashboard/dashboard.component.ts" region="getHeroes">
 </code-example>
 
 ### Add the dashboard route
@@ -224,29 +216,24 @@ To navigate to the dashboard, the router needs an appropriate route.
 
 Import the `DashboardComponent` in the `AppRoutingModule`.
 
-<code-example 
-  path="toh-pt5/src/app/app-routing.module.ts" 
-  region="import-dashboard" 
-  header="src/app/app-routing.module.ts (import DashboardComponent)">
+<code-example path="toh-pt5/src/app/app-routing.module.ts" region="import-dashboard" header="src/app/app-routing.module.ts (import DashboardComponent)">
 </code-example>
 
 Add a route to the `AppRoutingModule.routes` array that matches a path to the `DashboardComponent`.
 
-<code-example 
-  path="toh-pt5/src/app/app-routing.module.ts" 
-  region="dashboard-route">
+<code-example path="toh-pt5/src/app/app-routing.module.ts" header="src/app/app-routing.module.ts" region="dashboard-route">
 </code-example>
 
 ### Add a default route
 
-When the app starts, the browsers address bar points to the web site's root.
+When the app starts, the browser's address bar points to the web site's root.
 That doesn't match any existing route so the router doesn't navigate anywhere.
 The space below the `<router-outlet>` is blank.
 
 To make the app navigate to the dashboard automatically, add the following
 route to the `AppRoutingModule.Routes` array.
 
-<code-example path="toh-pt5/src/app/app-routing.module.ts" region="redirect-route">
+<code-example path="toh-pt5/src/app/app-routing.module.ts" header="src/app/app-routing.module.ts" region="redirect-route">
 </code-example>
 
 This route redirects a URL that fully matches the empty path to the route whose path is `'/dashboard'`.
@@ -292,36 +279,28 @@ The heroes list view should no longer show hero details as it does now.
 Open the `HeroesComponent` template (`heroes/heroes.component.html`) and
 delete the `<app-hero-detail>` element from the bottom.
 
-Clicking a hero item now does nothing. 
+Clicking a hero item now does nothing.
 You'll [fix that shortly](#heroes-component-links) after you enable routing to the `HeroDetailComponent`.
 
 ### Add a _hero detail_ route
 
-A URL like `~/detail/11` would be a good URL for navigating to the *Hero Detail* view of the hero whose `id` is `11`. 
+A URL like `~/detail/11` would be a good URL for navigating to the *Hero Detail* view of the hero whose `id` is `11`.
 
 Open `AppRoutingModule` and import `HeroDetailComponent`.
 
-<code-example 
-  path="toh-pt5/src/app/app-routing.module.ts" 
-  region="import-herodetail" 
-  header="src/app/app-routing.module.ts (import HeroDetailComponent)">
+<code-example path="toh-pt5/src/app/app-routing.module.ts" region="import-herodetail" header="src/app/app-routing.module.ts (import HeroDetailComponent)">
 </code-example>
 
 Then add a _parameterized_ route to the `AppRoutingModule.routes` array that matches the path pattern to the _hero detail_ view.
 
-<code-example 
-  path="toh-pt5/src/app/app-routing.module.ts" 
-  region="detail-route">
+<code-example path="toh-pt5/src/app/app-routing.module.ts" header="src/app/app-routing.module.ts" region="detail-route">
 </code-example>
 
 The colon (:) in the `path` indicates that `:id` is a placeholder for a specific hero `id`.
 
 At this point, all application routes are in place.
 
-<code-example 
-  path="toh-pt5/src/app/app-routing.module.ts" 
-  region="routes" 
-  header="src/app/app-routing.module.ts (all routes)">
+<code-example path="toh-pt5/src/app/app-routing.module.ts" region="routes" header="src/app/app-routing.module.ts (all routes)">
 </code-example>
 
 ### `DashboardComponent` hero links
@@ -331,14 +310,14 @@ The `DashboardComponent` hero links do nothing at the moment.
 Now that the router has a route to `HeroDetailComponent`,
 fix the dashboard hero links to navigate via the _parameterized_ dashboard route.
 
-<code-example 
-  path="toh-pt5/src/app/dashboard/dashboard.component.html" 
-  region="click" 
+<code-example
+  path="toh-pt5/src/app/dashboard/dashboard.component.html"
+  region="click"
   header="src/app/dashboard/dashboard.component.html (hero links)">
 </code-example>
 
-You're using Angular [interpolation binding](guide/template-syntax#interpolation) within the `*ngFor` repeater 
-to insert the current iteration's `hero.id` into each 
+You're using Angular [interpolation binding](guide/template-syntax#interpolation) within the `*ngFor` repeater
+to insert the current iteration's `hero.id` into each
 [`routerLink`](#routerlink).
 
 {@a heroes-component-links}
@@ -347,21 +326,15 @@ to insert the current iteration's `hero.id` into each
 The hero items in the `HeroesComponent` are `<li>` elements whose click events
 are bound to the component's `onSelect()` method.
 
-<code-example 
-  path="toh-pt4/src/app/heroes/heroes.component.html" 
-  region="list" 
-  header="src/app/heroes/heroes.component.html (list with onSelect)">
+<code-example path="toh-pt4/src/app/heroes/heroes.component.html" region="list" header="src/app/heroes/heroes.component.html (list with onSelect)">
 </code-example>
 
 Strip the `<li>` back to just its `*ngFor`,
 wrap the badge and name in an anchor element (`<a>`),
-and add a `routerLink` attribute to the anchor that 
+and add a `routerLink` attribute to the anchor that
 is the same as in the dashboard template
 
-<code-example 
-  path="toh-pt5/src/app/heroes/heroes.component.html" 
-  region="list" 
-  header="src/app/heroes/heroes.component.html (list with links)">
+<code-example path="toh-pt5/src/app/heroes/heroes.component.html" region="list" header="src/app/heroes/heroes.component.html (list with links)">
 </code-example>
 
 You'll have to fix the private stylesheet (`heroes.component.css`) to make
@@ -370,19 +343,16 @@ Revised styles are in the [final code review](#heroescomponent) at the bottom of
 
 #### Remove dead code (optional)
 
-While the `HeroesComponent` class still works, 
+While the `HeroesComponent` class still works,
 the `onSelect()` method and `selectedHero` property are no longer used.
 
 It's nice to tidy up and you'll be grateful to yourself later.
 Here's the class after pruning away the dead code.
 
-<code-example 
-  path="toh-pt5/src/app/heroes/heroes.component.ts"
-  region="class" 
-  header="src/app/heroes/heroes.component.ts (cleaned up)" linenums="false">
+<code-example path="toh-pt5/src/app/heroes/heroes.component.ts" region="class" header="src/app/heroes/heroes.component.ts (cleaned up)" linenums="false">
 </code-example>
 
-## Routable *HeroDetailComponent*
+## Routable `HeroDetailComponent`
 
 Previously, the parent `HeroesComponent` set the `HeroDetailComponent.hero`
 property and the `HeroDetailComponent` displayed the hero.
@@ -390,18 +360,16 @@ property and the `HeroDetailComponent` displayed the hero.
 `HeroesComponent` doesn't do that anymore.
 Now the router creates the `HeroDetailComponent` in response to a URL such as `~/detail/11`.
 
-The `HeroDetailComponent` needs a new way to obtain the _hero-to-display_.
+The `HeroDetailComponent` needs a new way to obtain the hero-to-display.
+This section explains the following:
 
-* Get the route that created it, 
+* Get the route that created it
 * Extract the `id` from the route
 * Acquire the hero with that `id` from the server via the `HeroService`
 
 Add the following imports:
 
-<code-example 
-  path="toh-pt5/src/app/hero-detail/hero-detail.component.ts" 
-  region="added-imports" 
-  header="src/app/hero-detail/hero-detail.component.ts">
+<code-example path="toh-pt5/src/app/hero-detail/hero-detail.component.ts" region="added-imports" header="src/app/hero-detail/hero-detail.component.ts">
 </code-example>
 
 {@a hero-detail-ctor}
@@ -409,27 +377,25 @@ Add the following imports:
 Inject the `ActivatedRoute`, `HeroService`, and `Location` services
 into the constructor, saving their values in private fields:
 
-<code-example 
-  path="toh-pt5/src/app/hero-detail/hero-detail.component.ts" region="ctor">
+<code-example path="toh-pt5/src/app/hero-detail/hero-detail.component.ts" header="toh-pt5/src/app/hero-detail/hero-detail.component.ts" region="ctor">
 </code-example>
 
 The [`ActivatedRoute`](api/router/ActivatedRoute) holds information about the route to this instance of the `HeroDetailComponent`.
-This component is interested in the route's bag of parameters extracted from the URL.
-The _"id"_ parameter is the `id` of the hero to display.
+This component is interested in the route's parameters extracted from the URL.
+The "id" parameter is the `id` of the hero to display.
 
 The [`HeroService`](tutorial/toh-pt4) gets hero data from the remote server
-and this component will use it to get the _hero-to-display_.
+and this component will use it to get the hero-to-display.
 
 The [`location`](api/common/Location) is an Angular service for interacting with the browser.
 You'll use it [later](#goback) to navigate back to the view that navigated here.
 
-### Extract the _id_ route parameter
+### Extract the `id` route parameter
 
 In the `ngOnInit()` [lifecycle hook](guide/lifecycle-hooks#oninit)
 call `getHero()` and define it as follows.
 
-<code-example 
-  path="toh-pt5/src/app/hero-detail/hero-detail.component.ts" region="ngOnInit">
+<code-example path="toh-pt5/src/app/hero-detail/hero-detail.component.ts" header="src/app/hero-detail/hero-detail.component.ts" region="ngOnInit">
 </code-example>
 
 The `route.snapshot` is a static image of the route information shortly after the component was created.
@@ -447,18 +413,14 @@ Add it now.
 
 ### Add `HeroService.getHero()`
 
-Open `HeroService` and add this `getHero()` method
+Open `HeroService` and add the following `getHero()` method with the `id` after the `getHeroes()` method:
 
-<code-example 
-  path="toh-pt5/src/app/hero.service.ts" 
-  region="getHero" 
-  header="src/app/hero.service.ts (getHero)">
+<code-example path="toh-pt5/src/app/hero.service.ts" region="getHero" header="src/app/hero.service.ts (getHero)">
 </code-example>
 
 <div class="alert is-important">
 
-Note the backticks ( &#96; ) that 
-define a JavaScript 
+Note the backticks ( &#96; ) that define a JavaScript
 [_template literal_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) for embedding the `id`.
 </div>
 
@@ -481,7 +443,7 @@ the router navigates to the detail view for the hero with `id: 11`,  "Dr Nice".
 
 ### Find the way back
 
-By clicking the browser's back button, 
+By clicking the browser's back button,
 you can go back to the hero list or dashboard view,
 depending upon which sent you to the detail view.
 
@@ -490,13 +452,10 @@ It would be nice to have a button on the `HeroDetail` view that can do that.
 Add a *go back* button to the bottom of the component template and bind it
 to the component's `goBack()` method.
 
-<code-example 
-  path="toh-pt5/src/app/hero-detail/hero-detail.component.html" 
-  region="back-button"
-  header="src/app/hero-detail/hero-detail.component.html (back button)">
+<code-example path="toh-pt5/src/app/hero-detail/hero-detail.component.html" region="back-button" header="src/app/hero-detail/hero-detail.component.html (back button)">
 </code-example>
 
-Add a `goBack()` _method_ to the component class that navigates backward one step 
+Add a `goBack()` _method_ to the component class that navigates backward one step
 in the browser's history stack
 using the `Location` service that you [injected previously](#hero-detail-ctor).
 
@@ -509,95 +468,93 @@ Refresh the browser and start clicking.
 Users can navigate around the app, from the dashboard to hero details and back,
 from heroes list to the mini detail to the hero details and back to the heroes again.
 
-You've met all of the navigational requirements that propelled this page.
-
 ## Final code review
 
 Here are the code files discussed on this page and your app should look like this <live-example></live-example>.
 
 {@a approutingmodule}
 {@a appmodule}
-#### _AppRoutingModule_, _AppModule_, and _HeroService_
+#### `AppRoutingModule`, `AppModule`, and `HeroService`
 
 <code-tabs>
-  <code-pane 
-    header="src/app/app-routing.module.ts" 
+  <code-pane
+    header="src/app/app-routing.module.ts"
     path="toh-pt5/src/app/app-routing.module.ts">
   </code-pane>
-  <code-pane 
-    header="src/app/app.module.ts" 
+  <code-pane
+    header="src/app/app.module.ts"
     path="toh-pt5/src/app/app.module.ts">
   </code-pane>
-  <code-pane 
-    header="src/app/hero.service.ts" 
+  <code-pane
+    header="src/app/hero.service.ts"
     path="toh-pt5/src/app/hero.service.ts">
   </code-pane>
 </code-tabs>
 
 {@a appcomponent}
-#### _AppComponent_
+#### `AppComponent`
 
 <code-tabs>
-  <code-pane 
+  <code-pane
     header="src/app/app.component.html"
     path="toh-pt5/src/app/app.component.html">
   </code-pane>
 
-  <code-pane 
+  <code-pane
     header="src/app/app.component.css"
     path="toh-pt5/src/app/app.component.css">
   </code-pane>
 </code-tabs>
 
 {@a dashboardcomponent}
-#### _DashboardComponent_
+#### `DashboardComponent`
 
 <code-tabs>
-  <code-pane 
+  <code-pane
     header="src/app/dashboard/dashboard.component.html" path="toh-pt5/src/app/dashboard/dashboard.component.html">
   </code-pane>
 
-  <code-pane 
+  <code-pane
     header="src/app/dashboard/dashboard.component.ts" path="toh-pt5/src/app/dashboard/dashboard.component.ts">
   </code-pane>
 
-  <code-pane 
+  <code-pane
     header="src/app/dashboard/dashboard.component.css" path="toh-pt5/src/app/dashboard/dashboard.component.css">
   </code-pane>
 </code-tabs>
 
 {@a heroescomponent}
-#### _HeroesComponent_
+#### `HeroesComponent`
 
 <code-tabs>
-  <code-pane 
+  <code-pane
     header="src/app/heroes/heroes.component.html" path="toh-pt5/src/app/heroes/heroes.component.html">
   </code-pane>
 
-  <code-pane 
-    header="src/app/heroes/heroes.component.ts" 
+  <code-pane
+    header="src/app/heroes/heroes.component.ts"
     path="toh-pt5/src/app/heroes/heroes.component.ts">
   </code-pane>
 
-  <code-pane 
-    header="src/app/heroes/heroes.component.css" 
+  <code-pane
+    header="src/app/heroes/heroes.component.css"
     path="toh-pt5/src/app/heroes/heroes.component.css">
   </code-pane>
 </code-tabs>
 
 {@a herodetailcomponent}
-#### _HeroDetailComponent_
+#### `HeroDetailComponent`
 
 <code-tabs>
-  <code-pane 
+  <code-pane
     header="src/app/hero-detail/hero-detail.component.html" path="toh-pt5/src/app/hero-detail/hero-detail.component.html">
   </code-pane>
 
-  <code-pane 
+  <code-pane
     header="src/app/hero-detail/hero-detail.component.ts" path="toh-pt5/src/app/hero-detail/hero-detail.component.ts">
   </code-pane>
 
-  <code-pane 
+  <code-pane
     header="src/app/hero-detail/hero-detail.component.css" path="toh-pt5/src/app/hero-detail/hero-detail.component.css">
   </code-pane>
 </code-tabs>
@@ -606,7 +563,7 @@ Here are the code files discussed on this page and your app should look like thi
 
 * You added the Angular router to navigate among different components.
 * You turned the `AppComponent` into a navigation shell with `<a>` links and a `<router-outlet>`.
-* You configured the router in an `AppRoutingModule` 
+* You configured the router in an `AppRoutingModule`
 * You defined simple routes, a redirect route, and a parameterized route.
 * You used the `routerLink` directive in anchor elements.
 * You refactored a tightly-coupled master/detail view into a routed detail view.

aio/content/tutorial/toh-pt6.md

@@ -11,174 +11,147 @@ When you're done with this page, the app should look like this <live-example></l
 
 ## Enable HTTP services
 
-`HttpClient` is Angular's mechanism for communicating with a remote server over HTTP. 
+`HttpClient` is Angular's mechanism for communicating with a remote server over HTTP.
 
-To make `HttpClient` available everywhere in the app:
+Make `HttpClient` available everywhere in the app in two steps. First, add it to the root `AppModule` by importing it:
 
-* open the root `AppModule` 
-* import the `HttpClientModule` symbol from `@angular/common/http`
-
-<code-example
-  path="toh-pt6/src/app/app.module.ts"
-  region="import-http-client"
-  header="src/app/app.module.ts (Http Client import)">
+<code-example path="toh-pt6/src/app/app.module.ts" region="import-http-client" header="src/app/app.module.ts (HttpClientModule import)">
+</code-example>
+
+Next, still in the `AppModule`, add `HttpClient` to the `imports` array:
+
+<code-example path="toh-pt6/src/app/app.module.ts" region="import-httpclientmodule" header="src/app/app.module.ts (imports array excerpt)">
 </code-example>
 
-* add it to the `@NgModule.imports` array
 
 ## Simulate a data server
 
-This tutorial sample _mimics_ communication with a remote data server by using the
-[_In-memory Web API_](https://github.com/angular/in-memory-web-api "In-memory Web API") module.
+This tutorial sample mimics communication with a remote data server by using the
+[In-memory Web API](https://github.com/angular/in-memory-web-api "In-memory Web API") module.
 
 After installing the module, the app will make requests to and receive responses from the `HttpClient`
 without knowing that the *In-memory Web API* is intercepting those requests,
 applying them to an in-memory data store, and returning simulated responses.
 
-This facility is a great convenience for the tutorial.
-You won't have to set up a server to learn about `HttpClient`.
-
-It may also be convenient in the early stages of your own app development when
-the server's web api is ill-defined or not yet implemented.
+By using the In-memory Web API, you won't have to set up a server to learn about `HttpClient`.
 
 <div class="alert is-important">
 
-**Important:** the *In-memory Web API* module has nothing to do with HTTP in Angular.
+**Important:** the In-memory Web API module has nothing to do with HTTP in Angular.
 
-If you're just _reading_ this tutorial to learn about `HttpClient`, you can [skip over](#import-heroes) this step.
-If you're _coding along_ with this tutorial, stay here and add the *In-memory Web API* now.
+If you're just reading this tutorial to learn about `HttpClient`, you can [skip over](#import-heroes) this step.
+If you're coding along with this tutorial, stay here and add the In-memory Web API now.
 
 </div>
 
-Install the *In-memory Web API* package from _npm_
+Install the In-memory Web API package from npm with the following command:
 
 <code-example language="sh" class="code-shell">
   npm install angular-in-memory-web-api --save
 </code-example>
 
+In the `AppModule`, import the `HttpClientInMemoryWebApiModule` and the `InMemoryDataService` class,
+which you will create in a moment.
 
-The class `src/app/in-memory-data.service.ts` is generated by the following command:
-
-<code-example language="sh" class="code-shell">
-  ng generate service InMemoryData
+<code-example path="toh-pt6/src/app/app.module.ts" region="import-in-mem-stuff" header="src/app/app.module.ts (In-memory Web API imports)">
 </code-example>
 
-This class has the following content:
+After the `HttpClientModule`, add the `HttpClientInMemoryWebApiModule`
+to the `AppModule` `imports` array and configure it with the `InMemoryDataService`.
 
-<code-example path="toh-pt6/src/app/in-memory-data.service.ts" region="init" header="src/app/in-memory-data.service.ts" linenums="false"></code-example>
-
-This file replaces `mock-heroes.ts`, which is now safe to delete.
-
-When your server is ready, detach the *In-memory Web API*, and the app's requests will go through to the server.
-
-Now back to the `HttpClient` story.
-
-Import the `HttpClientInMemoryWebApiModule` and the `InMemoryDataService` class.
-
-<code-example 
-  path="toh-pt6/src/app/app.module.ts" 
-  region="import-in-mem-stuff" 
-  header="src/app/app.module.ts (In-memory Web API imports)">
-</code-example>
-
-Add the `HttpClientInMemoryWebApiModule` to the `@NgModule.imports` array&mdash;
-_after importing the `HttpClientModule`_,
-&mdash;while configuring it with the `InMemoryDataService`.
-
-<code-example   
-  path="toh-pt6/src/app/app.module.ts" 
-  region="in-mem-web-api-imports">
+<code-example path="toh-pt6/src/app/app.module.ts" header="src/app/app.module.ts (imports array excerpt)" region="in-mem-web-api-imports">
 </code-example>
 
 The `forRoot()` configuration method takes an `InMemoryDataService` class
 that primes the in-memory database.
 
+Generate the class `src/app/in-memory-data.service.ts` with the following command:
+
+<code-example language="sh" class="code-shell">
+  ng generate service InMemoryData
+</code-example>
+
+Replace the default contents of `in-memory-data.service.ts` with the following:
+
+<code-example path="toh-pt6/src/app/in-memory-data.service.ts" region="init" header="src/app/in-memory-data.service.ts" linenums="false"></code-example>
+
+The `in-memory-data.service.ts` file replaces `mock-heroes.ts`, which is now safe to delete.
+
+When the server is ready, you'll detach the In-memory Web API, and the app's requests will go through to the server.
+
+
 {@a import-heroes}
 ## Heroes and HTTP
 
-Import some HTTP symbols that you'll need:
+In the `HeroService`, import `HttpClient` and `HttpHeaders`:
 
-<code-example
-  path="toh-pt6/src/app/hero.service.ts" 
-  region="import-httpclient" 
-  header="src/app/hero.service.ts (import HTTP symbols)">
+<code-example path="toh-pt6/src/app/hero.service.ts" region="import-httpclient" header="src/app/hero.service.ts (import HTTP symbols)">
 </code-example>
 
-Inject `HttpClient` into the constructor in a private property called `http`.
+Still in the `HeroService`, inject `HttpClient` into the constructor in a private property called `http`.
 
-<code-example 
-  path="toh-pt6/src/app/hero.service.ts" 
-  region="ctor" >
+<code-example path="toh-pt6/src/app/hero.service.ts" header="src/app/hero.service.ts" region="ctor" >
 </code-example>
 
-Keep injecting the `MessageService`. You'll call it so frequently that
-you'll wrap it in a private `log()` method.
+Notice that you keep injecting the `MessageService` but since you'll call it so frequently, wrap it in a private `log()` method:
 
-<code-example 
-  path="toh-pt6/src/app/hero.service.ts" 
-  region="log" >
+<code-example path="toh-pt6/src/app/hero.service.ts" header="src/app/hero.service.ts" region="log" >
 </code-example>
 
 Define the `heroesUrl` of the form `:base/:collectionName` with the address of the heroes resource on the server.
  Here `base` is the resource to which requests are made,
  and `collectionName` is the heroes data object in the `in-memory-data-service.ts`.
 
-<code-example 
-  path="toh-pt6/src/app/hero.service.ts" 
-  region="heroesUrl" >
+<code-example path="toh-pt6/src/app/hero.service.ts" header="src/app/hero.service.ts" region="heroesUrl" >
 </code-example>
 
-### Get heroes with _HttpClient_
+### Get heroes with `HttpClient`
 
-The current `HeroService.getHeroes()` 
+The current `HeroService.getHeroes()`
 uses the RxJS `of()` function to return an array of mock heroes
 as an `Observable<Hero[]>`.
 
-<code-example 
-  path="toh-pt4/src/app/hero.service.ts" 
-  region="getHeroes-1" 
-  header="src/app/hero.service.ts (getHeroes with RxJs 'of()')">
+<code-example path="toh-pt4/src/app/hero.service.ts" region="getHeroes-1" header="src/app/hero.service.ts (getHeroes with RxJs 'of()')">
 </code-example>
 
-Convert that method to use `HttpClient`
-<code-example 
-  path="toh-pt6/src/app/hero.service.ts" 
-  region="getHeroes-1">
+Convert that method to use `HttpClient` as follows:
+
+<code-example path="toh-pt6/src/app/hero.service.ts" header="src/app/hero.service.ts" region="getHeroes-1">
 </code-example>
 
 Refresh the browser. The hero data should successfully load from the
 mock server.
 
-You've swapped `of` for `http.get` and the app keeps working without any other changes
+You've swapped `of()` for `http.get()` and the app keeps working without any other changes
 because both functions return an `Observable<Hero[]>`.
 
-### Http methods return one value
+### `HttpClient` methods return one value
 
 All `HttpClient` methods return an RxJS `Observable` of something.
 
-HTTP is a request/response protocol. 
+HTTP is a request/response protocol.
 You make a request, it returns a single response.
 
 In general, an observable _can_ return multiple values over time.
 An observable from `HttpClient` always emits a single value and then completes, never to emit again.
 
-This particular `HttpClient.get` call returns an `Observable<Hero[]>`, literally "_an observable of hero arrays_". In practice, it will only return a single hero array.
+This particular `HttpClient.get()` call returns an `Observable<Hero[]>`; that is, "_an observable of hero arrays_". In practice, it will only return a single hero array.
 
-### _HttpClient.get_ returns response data
+### `HttpClient.get()` returns response data
 
-`HttpClient.get` returns the _body_ of the response as an untyped JSON object by default.
+`HttpClient.get()` returns the body of the response as an untyped JSON object by default.
 Applying the optional type specifier, `<Hero[]>` , gives you a typed result object.
 
-The shape of the JSON data is determined by the server's data API.
+The server's data API determines the shape of the JSON data.
 The _Tour of Heroes_ data API returns the hero data as an array.
 
 <div class="alert is-helpful">
 
 Other APIs may bury the data that you want within an object.
 You might have to dig that data out by processing the `Observable` result
-with the RxJS `map` operator.
+with the RxJS `map()` operator.
 
-Although not discussed here, there's an example of `map` in the `getHeroNo404()`
+Although not discussed here, there's an example of `map()` in the `getHeroNo404()`
 method included in the sample source code.
 
 </div>
@@ -192,59 +165,51 @@ To catch errors, you **"pipe" the observable** result from `http.get()` through
 
 Import the `catchError` symbol from `rxjs/operators`, along with some other operators you'll need later.
 
-<code-example 
-  path="toh-pt6/src/app/hero.service.ts" 
-  region="import-rxjs-operators">
+<code-example path="toh-pt6/src/app/hero.service.ts" header="src/app/hero.service.ts" region="import-rxjs-operators">
 </code-example>
 
-Now extend the observable result with the `.pipe()` method and
+Now extend the observable result with the `pipe()` method and
 give it a `catchError()` operator.
 
-<code-example 
-  path="toh-pt6/src/app/hero.service.ts" 
-  region="getHeroes-2" >
+<code-example path="toh-pt6/src/app/hero.service.ts" region="getHeroes-2" header="src/app/hero.service.ts">
 </code-example>
 
 The `catchError()` operator intercepts an **`Observable` that failed**.
-It passes the error an _error handler_ that can do what it wants with the error.
+It passes the error an error handler that can do what it wants with the error.
 
 The following `handleError()` method reports the error and then returns an
 innocuous result so that the application keeps working.
 
-#### _handleError_
+#### `handleError`
 
 The following `handleError()` will be shared by many `HeroService` methods
 so it's generalized to meet their different needs.
 
-Instead of handling the error directly, it returns an _error handler_ function to `catchError` that it 
+Instead of handling the error directly, it returns an error handler function to `catchError` that it
 has configured with both the name of the operation that failed and a safe return value.
 
-<code-example 
-  path="toh-pt6/src/app/hero.service.ts" 
-  region="handleError">
+<code-example path="toh-pt6/src/app/hero.service.ts" header="src/app/hero.service.ts" region="handleError">
 </code-example>
 
-After reporting the error to console, the handler constructs
-a user friendly message and returns a safe value to the app so it can keep working.
+After reporting the error to the console, the handler constructs
+a user friendly message and returns a safe value to the app so the app can keep working.
 
 Because each service method returns a different kind of `Observable` result,
 `handleError()` takes a type parameter so it can return the safe value as the type that the app expects.
 
-### Tap into the _Observable_
+### Tap into the Observable
 
 The `HeroService` methods will **tap** into the flow of observable values
-and send a message (via `log()`) to the message area at the bottom of the page.
+and send a message, via the `log()` method, to the message area at the bottom of the page.
 
-They'll do that with the RxJS `tap` operator,
-which _looks_ at the observable values, does _something_ with those values,
+They'll do that with the RxJS `tap()` operator,
+which looks at the observable values, does something with those values,
 and passes them along.
-The `tap` call back doesn't touch the values themselves.
+The `tap()` call back doesn't touch the values themselves.
 
-Here is the final version of `getHeroes` with the `tap` that logs the operation.
+Here is the final version of `getHeroes()` with the `tap()` that logs the operation.
 
-<code-example 
-  path="toh-pt6/src/app/hero.service.ts" 
-  region="getHeroes" >
+<code-example path="toh-pt6/src/app/hero.service.ts" header="src/app/hero.service.ts"  region="getHeroes" >
 </code-example>
 
 ### Get hero by id
@@ -254,20 +219,20 @@ Most web APIs support a _get by id_ request in the form `:baseURL/:id`.
 Here, the _base URL_ is the `heroesURL` defined in the [Heroes and HTTP](tutorial/toh-pt6#heroes-and-http) section (`api/heroes`) and _id_ is
 the number of the hero that you want to retrieve. For example, `api/heroes/11`.
 
-Add a `HeroService.getHero()` method to make that request:
+Update the `HeroService` `getHero()` method with the following to make that request:
 
 <code-example path="toh-pt6/src/app/hero.service.ts" region="getHero" header="src/app/hero.service.ts"></code-example>
 
-There are three significant differences from  `getHeroes()`.
+There are three significant differences from  `getHeroes()`:
 
-* it constructs a request URL with the desired hero's id.
-* the server should respond with a single hero rather than an array of heroes.
-* therefore, `getHero` returns an `Observable<Hero>` ("_an observable of Hero objects_")
+* `getHero()` constructs a request URL with the desired hero's id.
+* The server should respond with a single hero rather than an array of heroes.
+* `getHero()` returns an `Observable<Hero>` ("_an observable of Hero objects_")
  rather than an observable of hero _arrays_ .
 
 ## Update heroes
 
-Edit a hero's name in the _hero detail_ view.
+Edit a hero's name in the hero detail view.
 As you type, the hero name updates the heading at the top of the page.
 But when you click the "go back button", the changes are lost.
 
@@ -279,24 +244,21 @@ binding that invokes a new component method named `save()`.
 
 <code-example path="toh-pt6/src/app/hero-detail/hero-detail.component.html" region="save" header="src/app/hero-detail/hero-detail.component.html (save)"></code-example>
 
-Add the following `save()` method, which persists hero name changes using the hero service
+In the `HeroDetail` component class, add the following `save()` method, which persists hero name changes using the hero service
 `updateHero()` method and then navigates back to the previous view.
 
 <code-example path="toh-pt6/src/app/hero-detail/hero-detail.component.ts" region="save" header="src/app/hero-detail/hero-detail.component.ts (save)"></code-example>
 
-#### Add _HeroService.updateHero()_
+#### Add `HeroService.updateHero()`
 
 The overall structure of the `updateHero()` method is similar to that of
 `getHeroes()`, but it uses `http.put()` to persist the changed hero
-on the server.
+on the server. Add the following to the `HeroService`.
 
-<code-example 
-  path="toh-pt6/src/app/hero.service.ts" 
-  region="updateHero" 
-  header="src/app/hero.service.ts (update)">
+<code-example path="toh-pt6/src/app/hero.service.ts" region="updateHero" header="src/app/hero.service.ts (update)">
 </code-example>
 
-The `HttpClient.put()` method takes three parameters
+The `HttpClient.put()` method takes three parameters:
 * the URL
 * the data to update (the modified hero in this case)
 * options
@@ -304,20 +266,19 @@ The `HttpClient.put()` method takes three parameters
 The URL is unchanged. The heroes web API knows which hero to update by looking at the hero's `id`.
 
 The heroes web API expects a special header in HTTP save requests.
-That header is in the `httpOptions` constant defined in the `HeroService`.
+That header is in the `httpOptions` constant defined in the `HeroService`. Add the following to the `HeroService` class.
 
-<code-example 
-  path="toh-pt6/src/app/hero.service.ts" 
-  region="http-options"
-  header="src/app/hero.service.ts">
+<code-example path="toh-pt6/src/app/hero.service.ts" region="http-options" header="src/app/hero.service.ts">
 </code-example>
 
-Refresh the browser, change a hero name and save your change. Navigating to the previous view is implemented in the `save()` method defined in `HeroDetailComponent`.
+Refresh the browser, change a hero name and save your change. The `save()`
+method in `HeroDetailComponent`navigates to the previous view.
 The hero now appears in the list with the changed name.
 
+
 ## Add a new hero
 
-To add a hero, this app only needs the hero's name. You can use an `input`
+To add a hero, this app only needs the hero's name. You can use an `<input>`
 element paired with an add button.
 
 Insert the following into the `HeroesComponent` template, just after
@@ -325,29 +286,26 @@ the heading:
 
 <code-example path="toh-pt6/src/app/heroes/heroes.component.html" region="add" header="src/app/heroes/heroes.component.html (add)"></code-example>
 
-In response to a click event, call the component's click handler and then
-clear the input field so that it's ready for another name.
+In response to a click event, call the component's click handler, `add()`, and then
+clear the input field so that it's ready for another name. Add the following to the
+`HeroesComponent` class:
 
 <code-example path="toh-pt6/src/app/heroes/heroes.component.ts" region="add" header="src/app/heroes/heroes.component.ts (add)"></code-example>
 
 When the given name is non-blank, the handler creates a `Hero`-like object
 from the name (it's only missing the `id`) and passes it to the services `addHero()` method.
 
-When `addHero` saves successfully, the `subscribe` callback
+When `addHero()` saves successfully, the `subscribe()` callback
 receives the new hero and pushes it into to the `heroes` list for display.
 
-You'll write `HeroService.addHero` in the next section.
-
-#### Add _HeroService.addHero()_
-
 Add the following `addHero()` method to the `HeroService` class.
 
 <code-example path="toh-pt6/src/app/hero.service.ts" region="addHero" header="src/app/hero.service.ts (addHero)"></code-example>
 
-`HeroService.addHero()` differs from `updateHero` in two ways.
+`addHero()` differs from `updateHero()` in two ways:
 
-* it calls `HttpClient.post()` instead of `put()`.
-* it expects the server to generate an id for the new hero, 
+* It calls `HttpClient.post()` instead of `put()`.
+* It expects the server to generate an id for the new hero,
 which it returns in the `Observable<Hero>` to the caller.
 
 Refresh the browser and add some heroes.
@@ -359,7 +317,7 @@ Each hero in the heroes list should have a delete button.
 Add the following button element to the `HeroesComponent` template, after the hero
 name in the repeated `<li>` element.
 
-<code-example path="toh-pt6/src/app/heroes/heroes.component.html" region="delete"></code-example>
+<code-example path="toh-pt6/src/app/heroes/heroes.component.html" header="src/app/hero.service.ts" region="delete"></code-example>
 
 The HTML for the list of heroes should look like this:
 
@@ -369,7 +327,7 @@ To position the delete button at the far right of the hero entry,
 add some CSS to the `heroes.component.css`.  You'll find that CSS
 in the [final review code](#heroescomponent) below.
 
-Add the `delete()` handler to the component.
+Add the `delete()` handler to the component class.
 
 <code-example path="toh-pt6/src/app/heroes/heroes.component.ts" region="delete" header="src/app/heroes/heroes.component.ts (delete)"></code-example>
 
@@ -379,31 +337,29 @@ The component's `delete()` method immediately removes the _hero-to-delete_ from
 anticipating that the `HeroService` will succeed on the server.
 
 There's really nothing for the component to do with the `Observable` returned by
-`heroService.delete()`. **It must subscribe anyway**.
+`heroService.delete()` **but it must subscribe anyway**.
 
 <div class="alert is-important">
 
-  If you neglect to `subscribe()`, the service will not send the delete request to the server!
-  As a rule, an `Observable` _does nothing_ until something subscribes!
-  
+  If you neglect to `subscribe()`, the service will not send the delete request to the server.
+  As a rule, an `Observable` _does nothing_ until something subscribes.
+
   Confirm this for yourself by temporarily removing the `subscribe()`,
   clicking "Dashboard", then clicking "Heroes".
   You'll see the full list of heroes again.
 
 </div>
 
-#### Add _HeroService.deleteHero()_
-
-Add a `deleteHero()` method to `HeroService` like this.
+Next, add a `deleteHero()` method to `HeroService` like this.
 
 <code-example path="toh-pt6/src/app/hero.service.ts" region="deleteHero" header="src/app/hero.service.ts (delete)"></code-example>
 
-Note that
+Note the following key points:
 
-* it calls `HttpClient.delete`.
-* the URL is the heroes resource URL plus the `id` of the hero to delete
-* you don't send data as you did with `put` and `post`.
-* you still send the `httpOptions`.
+* `deleteHero()` calls `HttpClient.delete()`.
+* The URL is the heroes resource URL plus the `id` of the hero to delete.
+* You don't send data as you did with `put()` and `post()`.
+* You still send the `httpOptions`.
 
 Refresh the browser and try the new delete functionality.
 
@@ -413,43 +369,36 @@ In this last exercise, you learn to chain `Observable` operators together
 so you can minimize the number of similar HTTP requests
 and consume network bandwidth economically.
 
-You will add a *heroes search* feature to the *Dashboard*.
-As the user types a name into a search box, 
+You will add a heroes search feature to the Dashboard.
+As the user types a name into a search box,
 you'll make repeated HTTP requests for heroes filtered by that name.
 Your goal is to issue only as many requests as necessary.
 
-#### _HeroService.searchHeroes_
+#### `HeroService.searchHeroes()`
 
-Start by adding a `searchHeroes` method to the `HeroService`.
+Start by adding a `searchHeroes()` method to the `HeroService`.
 
-<code-example 
-  path="toh-pt6/src/app/hero.service.ts" 
-  region="searchHeroes"
-  header="src/app/hero.service.ts">
+<code-example path="toh-pt6/src/app/hero.service.ts" region="searchHeroes" header="src/app/hero.service.ts">
 </code-example>
 
 The method returns immediately with an empty array if there is no search term.
-The rest of it closely resembles `getHeroes()`.
-The only significant difference is the URL, 
-which includes a query string with the search term.
+The rest of it closely resembles `getHeroes()`, the only significant difference being
+the URL, which includes a query string with the search term.
 
 ### Add search to the Dashboard
 
-Open the `DashboardComponent` _template_ and
-Add the hero search element, `<app-hero-search>`, to the bottom of the `DashboardComponent` template.
+Open the `DashboardComponent` template and
+add the hero search element, `<app-hero-search>`, to the bottom of the markup.
 
-<code-example 
-  path="toh-pt6/src/app/dashboard/dashboard.component.html" header="src/app/dashboard/dashboard.component.html" linenums="false">
+<code-example path="toh-pt6/src/app/dashboard/dashboard.component.html" header="src/app/dashboard/dashboard.component.html" linenums="false">
 </code-example>
 
 This template looks a lot like the `*ngFor` repeater in the `HeroesComponent` template.
 
-Unfortunately, adding this element breaks the app.
-Angular can't find a component with a selector that matches `<app-hero-search>`.
+For this to work, the next step is to add a component with a selector that matches `<app-hero-search>`.
 
-The `HeroSearchComponent` doesn't exist yet. Fix that.
 
-### Create _HeroSearchComponent_
+### Create `HeroSearchComponent`
 
 Create a `HeroSearchComponent` with the CLI.
 
@@ -457,70 +406,62 @@ Create a `HeroSearchComponent` with the CLI.
   ng generate component hero-search
 </code-example>
 
-The CLI generates the three `HeroSearchComponent` files and adds the component to the `AppModule` declarations
+The CLI generates the three `HeroSearchComponent` files and adds the component to the `AppModule` declarations.
 
-Replace the generated `HeroSearchComponent` _template_ with a text box and a list of matching search results like this.
+Replace the generated `HeroSearchComponent` template with an `<input>` and a list of matching search results, as follows.
 
 <code-example path="toh-pt6/src/app/hero-search/hero-search.component.html" header="src/app/hero-search/hero-search.component.html"></code-example>
 
 Add private CSS styles to `hero-search.component.css`
 as listed in the [final code review](#herosearchcomponent) below.
 
-As the user types in the search box, an *input* event binding calls the component's `search()`
-method with the new search box value.
+As the user types in the search box, an input event binding calls the
+component's `search()` method with the new search box value.
 
 {@a asyncpipe}
 
-### _AsyncPipe_
+### `AsyncPipe`
 
-As expected, the `*ngFor` repeats hero objects.
+The `*ngFor` repeats hero objects. Notice that the `*ngFor` iterates over a list called `heroes$`, not `heroes`. The `$` is a convention that indicates `heroes$` is an `Observable`, not an array.
 
-Look closely and you'll see that the `*ngFor` iterates over a list called `heroes$`, not `heroes`.
 
-<code-example path="toh-pt6/src/app/hero-search/hero-search.component.html" region="async"></code-example>
+<code-example path="toh-pt6/src/app/hero-search/hero-search.component.html" header="src/app/hero-search/hero-search.component.html" region="async"></code-example>
 
-The `$` is a convention that indicates `heroes$` is an `Observable`, not an array.
-
-The `*ngFor` can't do anything with an `Observable`.
-But there's also a pipe character (`|`) followed by `async`,
-which identifies Angular's `AsyncPipe`.
-
-The `AsyncPipe` subscribes to an `Observable` automatically so you won't have to
+Since `*ngFor` can't do anything with an `Observable`, use the
+pipe character (`|`) followed by `async`. This identifies Angular's `AsyncPipe` and subscribes to an `Observable` automatically so you won't have to
 do so in the component class.
 
-### Fix the _HeroSearchComponent_ class
+### Edit the `HeroSearchComponent` class
 
 Replace the generated `HeroSearchComponent` class and metadata as follows.
 
 <code-example path="toh-pt6/src/app/hero-search/hero-search.component.ts" header="src/app/hero-search/hero-search.component.ts"></code-example>
 
-Notice the declaration of `heroes$` as an `Observable`
-<code-example 
-  path="toh-pt6/src/app/hero-search/hero-search.component.ts" 
-  region="heroes-stream">
+Notice the declaration of `heroes$` as an `Observable`:
+
+<code-example path="toh-pt6/src/app/hero-search/hero-search.component.ts" header="src/app/hero-search/hero-search.component.ts" region="heroes-stream">
 </code-example>
 
-You'll set it in [`ngOnInit()`](#search-pipe). 
+You'll set it in [`ngOnInit()`](#search-pipe).
 Before you do, focus on the definition of `searchTerms`.
 
-### The _searchTerms_ RxJS subject
+### The `searchTerms` RxJS subject
 
-The `searchTerms` property is declared as an RxJS `Subject`.
+The `searchTerms` property is an RxJS `Subject`.
 
-<code-example path="toh-pt6/src/app/hero-search/hero-search.component.ts" region="searchTerms"></code-example>
+<code-example path="toh-pt6/src/app/hero-search/hero-search.component.ts" header="src/app/hero-search/hero-search.component.ts" region="searchTerms"></code-example>
 
-A `Subject` is both a source of _observable_ values and an `Observable` itself.
+A `Subject` is both a source of observable values and an `Observable` itself.
 You can subscribe to a `Subject` as you would any `Observable`.
 
 You can also push values into that `Observable` by calling its `next(value)` method
 as the `search()` method does.
 
-The `search()` method is called via an _event binding_ to the
-textbox's `input` event.
+The event binding to the textbox's `input` event calls the `search()` method.
 
-<code-example path="toh-pt6/src/app/hero-search/hero-search.component.html" region="input"></code-example>
+<code-example path="toh-pt6/src/app/hero-search/hero-search.component.html" header="src/app/hero-search/hero-search.component.html" region="input"></code-example>
 
-Every time the user types in the textbox, the binding calls `search()` with the textbox value, a "search term". 
+Every time the user types in the textbox, the binding calls `search()` with the textbox value, a "search term".
 The `searchTerms` becomes an `Observable` emitting a steady stream of search terms.
 
 {@a search-pipe}
@@ -528,28 +469,24 @@ The `searchTerms` becomes an `Observable` emitting a steady stream of search ter
 ### Chaining RxJS operators
 
 Passing a new search term directly to the `searchHeroes()` after every user keystroke would create an excessive amount of HTTP requests,
-taxing server resources and burning through the cellular network data plan.
+taxing server resources and burning through data plans.
 
 Instead, the `ngOnInit()` method pipes the `searchTerms` observable through a sequence of RxJS operators that reduce the number of calls to the `searchHeroes()`,
 ultimately returning an observable of timely hero search results (each a `Hero[]`).
 
-Here's the code.
+Here's a closer look at the code.
 
-<code-example 
-  path="toh-pt6/src/app/hero-search/hero-search.component.ts" 
-  region="search">
+<code-example path="toh-pt6/src/app/hero-search/hero-search.component.ts" header="src/app/hero-search/hero-search.component.ts" region="search">
 </code-example>
 
-
+Each operator works as follows:
 
 * `debounceTime(300)` waits until the flow of new string events pauses for 300 milliseconds
 before passing along the latest string. You'll never make requests more frequently than 300ms.
 
-
 * `distinctUntilChanged()` ensures that a request is sent only if the filter text changed.
 
-
-* `switchMap()` calls the search service for each search term that makes it through `debounce` and `distinctUntilChanged`.
+* `switchMap()` calls the search service for each search term that makes it through `debounce()` and `distinctUntilChanged()`.
 It cancels and discards previous search observables, returning only the latest search service observable.
 
 
@@ -563,7 +500,7 @@ It cancels and discards previous search observables, returning only the latest s
   `switchMap()` preserves the original request order while returning only the observable from the most recent HTTP method call.
   Results from prior calls are canceled and discarded.
 
-  Note that _canceling_ a previous `searchHeroes()` _Observable_
+  Note that canceling a previous `searchHeroes()` Observable
   doesn't actually abort a pending HTTP request.
   Unwanted results are simply discarded before they reach your application code.
 
@@ -590,78 +527,78 @@ Here are the code files discussed on this page (all in the `src/app/` folder).
 {@a heroservice}
 {@a inmemorydataservice}
 {@a appmodule}
-#### _HeroService_, _InMemoryDataService_, _AppModule_
+#### `HeroService`, `InMemoryDataService`, `AppModule`
 
 <code-tabs>
-  <code-pane 
-    header="hero.service.ts" 
+  <code-pane
+    header="hero.service.ts"
     path="toh-pt6/src/app/hero.service.ts">
   </code-pane>
-  <code-pane 
+  <code-pane
     header="in-memory-data.service.ts"
     path="toh-pt6/src/app/in-memory-data.service.ts">
   </code-pane>
-  <code-pane 
-    header="app.module.ts" 
+  <code-pane
+    header="app.module.ts"
     path="toh-pt6/src/app/app.module.ts">
   </code-pane>
 </code-tabs>
 
 {@a heroescomponent}
-#### _HeroesComponent_
+#### `HeroesComponent`
 
 <code-tabs>
-  <code-pane 
-    header="heroes/heroes.component.html" 
+  <code-pane
+    header="heroes/heroes.component.html"
     path="toh-pt6/src/app/heroes/heroes.component.html">
   </code-pane>
-  <code-pane 
-    header="heroes/heroes.component.ts" 
+  <code-pane
+    header="heroes/heroes.component.ts"
     path="toh-pt6/src/app/heroes/heroes.component.ts">
   </code-pane>
-  <code-pane 
-    header="heroes/heroes.component.css" 
+  <code-pane
+    header="heroes/heroes.component.css"
     path="toh-pt6/src/app/heroes/heroes.component.css">
   </code-pane>
 </code-tabs>
 
 {@a herodetailcomponent}
-#### _HeroDetailComponent_
+#### `HeroDetailComponent`
 
 <code-tabs>
-  <code-pane 
+  <code-pane
     header="hero-detail/hero-detail.component.html"
     path="toh-pt6/src/app/hero-detail/hero-detail.component.html">
   </code-pane>
-  <code-pane 
-    header="hero-detail/hero-detail.component.ts" 
+  <code-pane
+    header="hero-detail/hero-detail.component.ts"
     path="toh-pt6/src/app/hero-detail/hero-detail.component.ts">
   </code-pane>
 </code-tabs>
 
 {@a dashboardcomponent}
-#### _DashboardComponent_
+#### `DashboardComponent`
 
 <code-tabs>
-  <code-pane 
+  <code-pane
     header="src/app/dashboard/dashboard.component.html"
     path="toh-pt6/src/app/dashboard/dashboard.component.html">
   </code-pane>
 </code-tabs>
 
 {@a herosearchcomponent}
-#### _HeroSearchComponent_
+#### `HeroSearchComponent`
 
 <code-tabs>
-  <code-pane 
+  <code-pane
     header="hero-search/hero-search.component.html"
     path="toh-pt6/src/app/hero-search/hero-search.component.html">
   </code-pane>
-  <code-pane 
+  <code-pane
     header="hero-search/hero-search.component.ts"
     path="toh-pt6/src/app/hero-search/hero-search.component.ts">
   </code-pane>
-  <code-pane 
+  <code-pane
     header="hero-search/hero-search.component.css"
     path="toh-pt6/src/app/hero-search/hero-search.component.css">
   </code-pane>

aio/karma.conf.js

@@ -10,17 +10,22 @@ module.exports = function (config) {
       require('karma-chrome-launcher'),
       require('karma-jasmine-html-reporter'),
       require('karma-coverage-istanbul-reporter'),
-      require('@angular-devkit/build-angular/plugins/karma')
+      require('@angular-devkit/build-angular/plugins/karma'),
+      {'reporter:jasmine-seed': ['type', JasmineSeedReporter]},
     ],
     client: {
-      clearContext: false // leave Jasmine Spec Runner output visible in browser
+      clearContext: false,  // leave Jasmine Spec Runner output visible in browser
+      jasmine: {
+        random: true,
+        seed: '',
+      },
     },
     coverageIstanbulReporter: {
       dir: require('path').join(__dirname, './coverage/site'),
       reports: ['html', 'lcovonly', 'text-summary'],
-      fixWebpackSourcePaths: true
+      fixWebpackSourcePaths: true,
     },
-    reporters: ['progress', 'kjhtml'],
+    reporters: ['progress', 'kjhtml', 'jasmine-seed'],
     port: 9876,
     colors: true,
     logLevel: config.LOG_INFO,
@@ -28,6 +33,18 @@ module.exports = function (config) {
     browsers: ['Chrome'],
     browserNoActivityTimeout: 60000,
     singleRun: false,
-    restartOnFileChange: true
+    restartOnFileChange: true,
   });
 };
+
+// Helpers
+function JasmineSeedReporter(baseReporterDecorator) {
+  baseReporterDecorator(this);
+
+  this.onBrowserComplete = (browser, result) => {
+    const seed = result.order && result.order.random && result.order.seed;
+    if (seed) this.write(`${browser}: Randomized with seed ${seed}.\n`);
+  };
+
+  this.onRunComplete = () => undefined;
+}

aio/package.json

@@ -19,7 +19,7 @@
     "build-local": "yarn ~~build",
     "prebuild-with-ivy": "yarn setup-local && node scripts/switch-to-ivy",
     "build-with-ivy": "yarn ~~build",
-    "extract-cli-command-docs": "node tools/transforms/cli-docs-package/extract-cli-commands.js 01a7186bb",
+    "extract-cli-command-docs": "node tools/transforms/cli-docs-package/extract-cli-commands.js f99913e9f",
     "lint": "yarn check-env && yarn docs-lint && ng lint && yarn example-lint && yarn tools-lint",
     "test": "yarn check-env && ng test",
     "pree2e": "yarn check-env && yarn update-webdriver",
@@ -33,8 +33,10 @@
     "set-opensearch-url": "node --eval \"const sh = require('shelljs'); sh.set('-e'); sh.sed('-i', /PLACEHOLDER_URL/g, process.argv[1], 'dist/assets/opensearch.xml');\"",
     "presmoke-tests": "yarn update-webdriver",
     "smoke-tests": "protractor tests/deployment/e2e/protractor.conf.js --suite smoke --baseUrl",
-    "test-pwa-score": "node scripts/test-pwa-score",
-    "test-pwa-score-localhost": "run-p --race \"~~http-server dist -p 4200 --silent\" \"test-pwa-score http://localhost:4200 {1} {2}\" --",
+    "test-a11y-score": "node scripts/test-aio-a11y",
+    "test-a11y-score-localhost": "run-p --race \"~~light-server -s dist -p 4200 --quiet\" \"test-a11y-score http://localhost:4200\" --",
+    "test-pwa-score": "run-s \"~~audit-web-app {1} all:0,pwa:{2} {3}\" --",
+    "test-pwa-score-localhost": "run-p --race \"~~light-server -s dist -p 4200 --quiet\" \"test-pwa-score http://localhost:4200 {1} {2}\" --",
     "example-e2e": "yarn example-check-local && node ./tools/examples/run-example-e2e",
     "example-lint": "tslint --config \"content/examples/tslint.json\" \"content/examples/**/*.ts\" --exclude \"content/examples/styleguide/**/*.avoid.ts\"",
     "example-use-local": "node tools/ng-packages-installer overwrite ./tools/examples/shared --debug",
@@ -64,15 +66,16 @@
     "generate-zips": "node ./tools/example-zipper/generateZips",
     "build-404-page": "node scripts/build-404-page",
     "update-webdriver": "webdriver-manager update --standalone false --gecko false $CI_CHROMEDRIVER_VERSION_ARG",
+    "~~audit-web-app": "node scripts/audit-web-app",
     "~~check-env": "node scripts/check-environment",
     "~~clean-generated": "node --eval \"require('shelljs').rm('-rf', 'src/generated')\"",
     "~~build": "ng build --configuration=stable",
     "post~~build": "yarn build-404-page",
-    "~~http-server": "http-server"
+    "~~light-server": "light-server --bind=localhost --historyindex=/index.html --no-reload"
   },
   "engines": {
     "node": ">=10.9.0 <11.0.0",
-    "yarn": ">=1.12.1 <=1.14.0"
+    "yarn": ">=1.12.1 <=1.16.0"
   },
   "private": true,
   "dependencies": {
@@ -106,13 +109,13 @@
     "archiver": "^1.3.0",
     "canonical-path": "1.0.0",
     "chalk": "^2.1.0",
-    "chrome-launcher": "^0.10.5",
+    "chrome-launcher": "^0.10.7",
     "cjson": "^0.5.0",
     "codelyzer": "^5.0.0",
     "cross-spawn": "^5.1.0",
     "css-selector-parser": "^1.3.0",
     "dgeni": "^0.4.11",
-    "dgeni-packages": "^0.27.1",
+    "dgeni-packages": "^0.27.5",
     "entities": "^1.1.1",
     "eslint": "^3.19.0",
     "eslint-plugin-jasmine": "^2.2.0",
@@ -123,24 +126,23 @@
     "hast-util-is-element": "^1.0.0",
     "hast-util-to-string": "^1.0.0",
     "html": "^1.0.0",
-    "http-server": "^0.11.1",
     "ignore": "^3.3.3",
     "image-size": "^0.5.1",
-    "jasmine": "^2.6.0",
-    "jasmine-core": "^2.8.0",
-    "jasmine-marbles": "^0.3.1",
-    "jasmine-spec-reporter": "^4.1.0",
+    "jasmine": "^3.4.0",
+    "jasmine-core": "^3.4.0",
+    "jasmine-spec-reporter": "^4.2.1",
     "jasmine-ts": "^0.2.1",
     "jsdom": "^9.12.0",
     "json-schema-traverse": "^0.4.1",
     "json5": "^1.0.1",
-    "karma": "^1.7.0",
-    "karma-chrome-launcher": "^2.1.1",
-    "karma-cli": "^1.0.1",
-    "karma-coverage-istanbul-reporter": "^1.3.0",
-    "karma-jasmine": "^1.1.0",
-    "karma-jasmine-html-reporter": "^0.2.2",
-    "lighthouse": "^4.3.0",
+    "karma": "^4.1.0",
+    "karma-chrome-launcher": "^2.2.0",
+    "karma-cli": "^2.0.0",
+    "karma-coverage-istanbul-reporter": "^2.0.5",
+    "karma-jasmine": "^2.0.1",
+    "karma-jasmine-html-reporter": "^1.4.2",
+    "light-server": "^2.6.2",
+    "lighthouse": "^5.1.0",
     "lighthouse-logger": "^1.2.0",
     "lodash": "^4.17.4",
     "lunr": "^2.1.0",
@@ -167,4 +169,4 @@
     "xregexp": "^4.0.0",
     "yargs": "^7.0.2"
   }
-}
+}

aio/scripts/audit-web-app.js

@@ -0,0 +1,179 @@
+#!/bin/env node
+'use strict';
+
+/**
+ * Usage:
+ * ```sh
+ * node scripts/audit-web-app <url> <min-scores> [<log-file>]
+ * ```
+ *
+ * Runs audits against the specified URL on specific categories (accessibility, best practices, performance, PWA, SEO).
+ * It fails, if the score in any category is below the score specified in `<min-scores>`. (Only runs audits for the
+ * specified categories.)
+ *
+ * `<min-scores>` is either a number (in which case it is interpreted as `all:<min-score>`) or a list of comma-separated
+ * strings of the form `key:value`, where `key` is one of `accessibility`, `best-practices`, `performance`, `pwa`, `seo`
+ * or `all` and `value` is a number (between 0 and 100).
+ *
+ * Examples:
+ * - `95` _(Same as `all:95`.)_
+ * - `all:95` _(Run audits for all categories and require a score of 95 or higher.)_
+ * - `all:95,pwa:100` _(Same as `all:95`, except that a scope of 100 is required for the `pwa` category.)_
+ * - `performance:90` _(Only run audits for the `performance` category and require a score of 90 or higher.)_
+ *
+ * If `<log-file>` is defined, the full results will be logged there.
+ *
+ * (Skips HTTPS-related audits, when run for an HTTP URL.)
+ */
+
+// Imports
+const chromeLauncher = require('chrome-launcher');
+const lighthouse = require('lighthouse');
+const printer = require('lighthouse/lighthouse-cli/printer');
+const logger = require('lighthouse-logger');
+
+// Constants
+const AUDIT_CATEGORIES = ['accessibility', 'best-practices', 'performance', 'pwa', 'seo'];
+const CHROME_LAUNCH_OPTS = {chromeFlags: ['--headless']};
+const LIGHTHOUSE_FLAGS = {logLevel: process.env.CI ? 'error' : 'info'};  // Be less verbose on CI.
+const SKIPPED_HTTPS_AUDITS = ['redirects-http', 'uses-http2'];
+const VIEWER_URL = 'https://googlechrome.github.io/lighthouse/viewer';
+const WAIT_FOR_SW_DELAY = 5000;
+
+// Run
+_main(process.argv.slice(2));
+
+// Functions - Definitions
+async function _main(args) {
+  const {url, minScores, logFile} = parseInput(args);
+  const isOnHttp = /^http:/.test(url);
+  const lhFlags = {...LIGHTHOUSE_FLAGS, onlyCategories: Object.keys(minScores).sort()};
+  const lhConfig = {
+    extends: 'lighthouse:default',
+    // Since the Angular ServiceWorker waits for the app to stabilize before registering,
+    // wait a few seconds after load to allow Lighthouse to reliably detect it.
+    passes: [{passName: 'defaultPass', pauseAfterLoadMs: WAIT_FOR_SW_DELAY}],
+  };
+
+  console.log(`Running web-app audits for '${url}'...`);
+  console.log(`  Audit categories: ${lhFlags.onlyCategories.join(', ')}`);
+
+  // If testing on HTTP, skip HTTPS-specific tests.
+  // (Note: Browsers special-case localhost and run ServiceWorker even on HTTP.)
+  if (isOnHttp) skipHttpsAudits(lhConfig);
+
+  logger.setLevel(lhFlags.logLevel);
+
+  try {
+    console.log('');
+    const startTime = Date.now();
+    const results = await launchChromeAndRunLighthouse(url, lhFlags, lhConfig);
+    const success = await processResults(results, minScores, logFile);
+    console.log(`\n(Completed in ${((Date.now() - startTime) / 1000).toFixed(1)}s.)\n`);
+
+    if (!success) {
+      throw new Error('One or more scores are too low.');
+    }
+  } catch (err) {
+    onError(err);
+  }
+}
+
+function formatScore(score) {
+  return `${(score * 100).toFixed(0).padStart(3)}`;
+}
+
+async function launchChromeAndRunLighthouse(url, flags, config) {
+  const chrome = await chromeLauncher.launch(CHROME_LAUNCH_OPTS);
+  flags.port = chrome.port;
+
+  try {
+    return await lighthouse(url, flags, config);
+  } finally {
+    await chrome.kill();
+  }
+}
+
+function onError(err) {
+  console.error(err);
+  console.error('');
+  process.exit(1);
+}
+
+function parseInput(args) {
+  const [url, minScoresRaw, logFile] = args;
+
+  if (!url) {
+    onError('Invalid arguments: <url> not specified.');
+  } else if (!minScoresRaw) {
+    onError('Invalid arguments: <min-scores> not specified.');
+  }
+
+  const minScores = parseMinScores(minScoresRaw || '');
+  const unknownCategories = Object.keys(minScores).filter(cat => !AUDIT_CATEGORIES.includes(cat));
+  const allValuesValid = Object.values(minScores).every(x => (0 <= x) && (x <= 1));
+
+  if (unknownCategories.length > 0) {
+    onError(`Invalid arguments: <min-scores> contains unknown category(-ies): ${unknownCategories.join(', ')}`);
+  } else if (!allValuesValid) {
+    onError(`Invalid arguments: <min-scores> has non-numeric or out-of-range values: ${minScoresRaw}`);
+  }
+
+  return {url, minScores, logFile};
+}
+
+function parseMinScores(raw) {
+  const minScores = {};
+
+  if (/^\d+$/.test(raw)) {
+    raw = `all:${raw}`;
+  }
+
+  raw.
+    split(',').
+    map(x => x.split(':')).
+    forEach(([key, val]) => minScores[key] = Number(val) / 100);
+
+  if (minScores.hasOwnProperty('all')) {
+    AUDIT_CATEGORIES.forEach(cat => minScores.hasOwnProperty(cat) || (minScores[cat] = minScores.all));
+    delete minScores.all;
+  }
+
+  return minScores;
+}
+
+async function processResults(results, minScores, logFile) {
+  const lhVersion = results.lhr.lighthouseVersion;
+  const categories = results.lhr.categories;
+  const report = results.report;
+
+  if (logFile) {
+    console.log(`\nSaving results in '${logFile}'...`);
+    console.log(`  LightHouse viewer: ${VIEWER_URL}`);
+
+    await printer.write(report, printer.OutputMode.json, logFile);
+  }
+
+  console.log(`\nLighthouse version: ${lhVersion}`);
+  console.log('\nAudit results:');
+
+  const maxTitleLen = Math.max(...Object.values(categories).map(({title}) => title.length));
+  const success = Object.keys(categories).sort().reduce((aggr, cat) => {
+    const {title, score} = categories[cat];
+    const paddedTitle = `${title}:`.padEnd(maxTitleLen + 1);
+    const minScore = minScores[cat];
+    const passed = !isNaN(score) && (score >= minScore);
+
+    console.log(
+      `  - ${paddedTitle}  ${formatScore(score)}  (Required: ${formatScore(minScore)})  ${passed ? 'OK' : 'FAILED'}`);
+
+    return aggr && passed;
+  }, true);
+
+  return success;
+}
+
+function skipHttpsAudits(config) {
+  console.log(`  Skipping HTTPS-related audits: ${SKIPPED_HTTPS_AUDITS.join(', ')}`);
+  config.settings = {...config.settings, skipAudits: SKIPPED_HTTPS_AUDITS};
+}

aio/scripts/test-aio-a11y.js

@@ -0,0 +1,38 @@
+#!/bin/env node
+'use strict';
+
+/**
+ * Usage:
+ * ```sh
+ * node scripts/test-aio-a11y <origin>
+ * ```
+ *
+ * Runs accessibility audits on several (pre-defined) pages on the specified origin. It fails, if
+ * the score for any page is below the minimum (see `MIN_SCORES_PER_PAGE` below).
+ *
+ * `<origin>` is the origin (scheme + hostname + port) of an angular.io deployment. It can be remote
+ * (e.g. `https://next.angular.io`) or local (e.g. `http://localhost:4200`).
+ */
+
+// Imports
+const sh = require('shelljs');
+sh.set('-e');
+
+// Constants
+const MIN_SCORES_PER_PAGE = {
+  '': 100,
+  'api': 100,
+  'api/core/Directive': 90,
+  'cli': 91,
+  'cli/add': 91,
+  'docs': 100,
+  'guide/docs-style-guide': 88,
+  'start': 90,
+};
+
+// Run
+const auditWebAppCmd = `"${process.execPath}" "${__dirname}/audit-web-app"`;
+const origin = process.argv[2];
+for (const [page, minScore] of Object.entries(MIN_SCORES_PER_PAGE)) {
+  sh.exec(`${auditWebAppCmd} ${origin}/${page} accessibility:${minScore}`);
+}

aio/scripts/test-production.sh

@@ -25,5 +25,8 @@ set +x -eu -o pipefail
   # Run PWA-score tests.
   yarn test-pwa-score "$targetUrl" "$minPwaScore"
 
+  # Run a11y tests.
+  yarn test-a11y-score "$targetUrl"
+
   echo -e "\nAll checks passed!"
 )

aio/scripts/test-pwa-score.js

@@ -1,135 +0,0 @@
-#!/bin/env node
-
-/**
- * Usage:
- * ```sh
- * node scripts/test-pwa-score <url> <min-score> [<log-file>]
- * ```
- *
- * Fails if the score is below `<min-score>`.
- * If `<log-file>` is defined, the full results will be logged there.
- *
- * (Skips HTTPS-related audits, when run for HTTP URL.)
- */
-
-// Imports
-const chromeLauncher = require('chrome-launcher');
-const lighthouse = require('lighthouse');
-const printer = require('lighthouse/lighthouse-cli/printer');
-const logger = require('lighthouse-logger');
-
-// Constants
-const CHROME_LAUNCH_OPTS = {};
-const LIGHTHOUSE_FLAGS = {logLevel: 'info'};
-const SKIPPED_HTTPS_AUDITS = ['redirects-http'];
-const VIEWER_URL = 'https://googlechrome.github.io/lighthouse/viewer/';
-const WAIT_FOR_SW_DELAY = 5000;
-
-// Be less verbose on CI.
-if (process.env.CI) {
-  LIGHTHOUSE_FLAGS.logLevel = 'error';
-}
-
-// Run
-_main(process.argv.slice(2));
-
-// Functions - Definitions
-async function _main(args) {
-  const {url, minScore, logFile} = parseInput(args);
-  const isOnHttp = /^http:/.test(url);
-  const config = {
-    extends: 'lighthouse:default',
-    // Since the Angular ServiceWorker waits for the app to stabilize before registering,
-    // wait a few seconds after load to allow Lighthouse to reliably detect it.
-    passes: [{passName: 'defaultPass', pauseAfterLoadMs: WAIT_FOR_SW_DELAY}],
-  }
-
-  console.log(`Running PWA audit for '${url}'...`);
-
-  // If testing on HTTP, skip HTTPS-specific tests.
-  // (Note: Browsers special-case localhost and run ServiceWorker even on HTTP.)
-  if (isOnHttp) skipHttpsAudits(config);
-
-  logger.setLevel(LIGHTHOUSE_FLAGS.logLevel);
-
-  try {
-    const results = await launchChromeAndRunLighthouse(url, LIGHTHOUSE_FLAGS, config);
-    const score = await processResults(results, logFile);
-    evaluateScore(minScore, score);
-  } catch (err) {
-    onError(err);
-  }
-}
-
-function evaluateScore(expectedScore, actualScore) {
-  console.log('\nLighthouse PWA score:');
-  console.log(`  - Expected: ${expectedScore.toFixed(0).padStart(3)} / 100 (or higher)`);
-  console.log(`  - Actual:   ${actualScore.toFixed(0).padStart(3)} / 100\n`);
-
-  if (isNaN(actualScore) || (actualScore < expectedScore)) {
-    throw new Error(`PWA score is too low. (${actualScore} < ${expectedScore})`);
-  }
-}
-
-async function launchChromeAndRunLighthouse(url, flags, config) {
-  const chrome = await chromeLauncher.launch(CHROME_LAUNCH_OPTS);
-  flags.port = chrome.port;
-
-  try {
-    return await lighthouse(url, flags, config);
-  } finally {
-    await chrome.kill();
-  }
-}
-
-function onError(err) {
-  console.error(err);
-  process.exit(1);
-}
-
-function parseInput(args) {
-  const url = args[0];
-  const minScore = Number(args[1]);
-  const logFile = args[2];
-
-  if (!url) {
-    onError('Invalid arguments: <URL> not specified.');
-  } else if (isNaN(minScore)) {
-    onError('Invalid arguments: <MIN_SCORE> not specified or not a number.');
-  }
-
-  return {url, minScore, logFile};
-}
-
-async function processResults(results, logFile) {
-  const lhVersion = results.lhr.lighthouseVersion;
-  const categories = results.lhr.categories;
-  const report = results.report;
-
-  if (logFile) {
-    console.log(`\nSaving results in '${logFile}'...`);
-    console.log(`(LightHouse viewer: ${VIEWER_URL})`);
-
-    await printer.write(report, printer.OutputMode.json, logFile);
-  }
-
-  const categoryData = Object.keys(categories).map(name => categories[name]);
-  const maxTitleLen = Math.max(...categoryData.map(({title}) => title.length));
-
-  console.log(`\nLighthouse version: ${lhVersion}`);
-
-  console.log('\nAudit scores:');
-  categoryData.forEach(({title, score}) => {
-    const paddedTitle = `${title}:`.padEnd(maxTitleLen + 1);
-    const paddedScore = (score * 100).toFixed(0).padStart(3);
-    console.log(`  - ${paddedTitle} ${paddedScore} / 100`);
-  });
-
-  return categories.pwa.score * 100;
-}
-
-function skipHttpsAudits(config) {
-  console.info(`Skipping HTTPS-related audits (${SKIPPED_HTTPS_AUDITS.join(', ')})...`);
-  const settings = config.settings || (config.settings = {});
-  settings.skipAudits = SKIPPED_HTTPS_AUDITS;
-}

aio/src/app/app.component.spec.ts

@@ -630,6 +630,11 @@ describe('AppComponent', () => {
       };
 
 
+      beforeEach(() => {
+        tocContainer = null;
+        toc = null;
+      });
+
       it('should show/hide `<aio-toc>` based on `hasFloatingToc`', () => {
         expect(tocContainer).toBeFalsy();
         expect(toc).toBeFalsy();

aio/src/app/custom-elements/announcement-bar/announcement-bar.component.spec.ts

@@ -40,6 +40,7 @@ describe('AnnouncementBarComponent', () => {
     it('should make a single request to the server', () => {
       component.ngOnInit();
       httpMock.expectOne('generated/announcements.json');
+      expect().nothing();  // Prevent jasmine from complaining about no expectations.
     });
 
     it('should set the announcement to the first "live" one in the list loaded from `announcements.json`', () => {

aio/src/app/custom-elements/api/api-list.component.html

@@ -15,7 +15,7 @@
   </aio-select>
 
   <div class="form-search">
-    <input #filter placeholder="Filter" (input)="setQuery($event.target.value)">
+    <input #filter placeholder="Filter" (input)="setQuery($event.target.value)" aria-label="Filter Search">
     <i class="material-icons">search</i>
   </div>
 </div>

aio/src/app/custom-elements/api/api.service.spec.ts

@@ -29,6 +29,7 @@ describe('ApiService', () => {
 
   it('should not immediately connect to the server', () => {
     httpMock.expectNone({});
+    expect().nothing();  // Prevent jasmine from complaining about no expectations.
   });
 
   it('subscribers should be completed/unsubscribed when service destroyed', () => {
@@ -91,6 +92,7 @@ describe('ApiService', () => {
     it('should connect to the server w/ expected URL', () => {
       service.fetchSections();
       httpMock.expectOne('generated/docs/api/api-list.json');
+      expect().nothing();  // Prevent jasmine from complaining about no expectations.
     });
 
     it('should refresh the #sections observable w/ new content on second call', () => {

aio/src/app/custom-elements/code/code-example.component.spec.ts

@@ -5,6 +5,8 @@ import { CodeExampleComponent } from './code-example.component';
 import { CodeExampleModule } from './code-example.module';
 import { Logger } from 'app/shared/logger.service';
 import { MockLogger } from 'testing/logger.service';
+import { MockPrettyPrinter } from 'testing/pretty-printer.service';
+import { PrettyPrinter } from './pretty-printer.service';
 
 describe('CodeExampleComponent', () => {
   let hostComponent: HostComponent;
@@ -19,6 +21,7 @@ describe('CodeExampleComponent', () => {
       ],
       providers: [
         { provide: Logger, useClass: MockLogger },
+        { provide: PrettyPrinter, useClass: MockPrettyPrinter },
       ]
     });
 

aio/src/app/custom-elements/code/code-tabs.component.spec.ts

@@ -2,10 +2,12 @@ import { Component, ViewChild, NO_ERRORS_SCHEMA } from '@angular/core';
 import { ComponentFixture, TestBed } from '@angular/core/testing';
 import { Logger } from 'app/shared/logger.service';
 import { MockLogger } from 'testing/logger.service';
+import { MockPrettyPrinter } from 'testing/pretty-printer.service';
 import { NoopAnimationsModule } from '@angular/platform-browser/animations';
 
 import { CodeTabsComponent } from './code-tabs.component';
 import { CodeTabsModule } from './code-tabs.module';
+import { PrettyPrinter } from './pretty-printer.service';
 
 describe('CodeTabsComponent', () => {
   let fixture: ComponentFixture<HostComponent>;
@@ -19,6 +21,7 @@ describe('CodeTabsComponent', () => {
       schemas: [ NO_ERRORS_SCHEMA ],
       providers: [
        { provide: Logger, useClass: MockLogger },
+       { provide: PrettyPrinter, useClass: MockPrettyPrinter },
       ]
     });
 

aio/src/app/custom-elements/code/code.component.spec.ts

@@ -1,114 +1,104 @@
 import { Component, ViewChild, AfterViewInit } from '@angular/core';
-import { async, ComponentFixture, TestBed } from '@angular/core/testing';
+import { ComponentFixture, TestBed } from '@angular/core/testing';
 import { MatSnackBar } from '@angular/material/snack-bar';
 import { By } from '@angular/platform-browser';
 import { NoopAnimationsModule } from '@angular/platform-browser/animations';
-import { first } from 'rxjs/operators';
 
 import { CodeComponent } from './code.component';
 import { CodeModule } from './code.module';
 import { CopierService } from 'app/shared//copier.service';
 import { Logger } from 'app/shared/logger.service';
+import { MockPrettyPrinter } from 'testing/pretty-printer.service';
 import { PrettyPrinter } from './pretty-printer.service';
 
 const oneLineCode = 'const foo = "bar";';
 
-const smallMultiLineCode = `
-<hero-details>
+const smallMultiLineCode =
+`<hero-details>
   <h2>Bah Dah Bing</h2>
   <hero-team>
     <h3>NYC Team</h3>
   </hero-team>
 </hero-details>`;
 
-const bigMultiLineCode = smallMultiLineCode + smallMultiLineCode + smallMultiLineCode;
+const bigMultiLineCode = `${smallMultiLineCode}\n${smallMultiLineCode}\n${smallMultiLineCode}`;
 
 describe('CodeComponent', () => {
   let hostComponent: HostComponent;
   let fixture: ComponentFixture<HostComponent>;
 
-  // WARNING: Chance of cross-test pollution
-  // CodeComponent injects PrettyPrintService
-  // Once PrettyPrintService runs once _anywhere_, its ctor loads `prettify.js`
-  // which sets `window['prettyPrintOne']`
-  // That global survives these tests unless
-  // we take strict measures to wipe it out in the `afterAll`
-  // and make sure THAT runs after the tests by making component creation async
-  afterAll(() => {
-    delete (window as any)['prettyPrint'];
-    delete (window as any)['prettyPrintOne'];
-  });
-
   beforeEach(() => {
     TestBed.configureTestingModule({
       imports: [ NoopAnimationsModule, CodeModule ],
       declarations: [ HostComponent ],
       providers: [
-        PrettyPrinter,
         CopierService,
-        {provide: Logger, useClass: TestLogger }
+        { provide: Logger, useClass: TestLogger },
+        { provide: PrettyPrinter, useClass: MockPrettyPrinter },
      ]
-    }).compileComponents();
-  });
+    });
 
-  // Must be async because
-  // CodeComponent creates PrettyPrintService which async loads `prettify.js`.
-  // If not async, `afterAll` finishes before tests do!
-  beforeEach(async(() => {
     fixture = TestBed.createComponent(HostComponent);
     hostComponent = fixture.componentInstance;
 
     fixture.detectChanges();
-  }));
+  });
 
   describe('pretty printing', () => {
-    const untilCodeFormatted = () => {
-      const emitter = hostComponent.codeComponent.codeFormatted;
-      return emitter.pipe(first()).toPromise();
-    };
-    const hasLineNumbers = async () => {
-      // presence of `<li>`s are a tell-tale for line numbers
-      await untilCodeFormatted();
-      return 0 < fixture.nativeElement.querySelectorAll('li').length;
-    };
+    const getFormattedCode = () => fixture.nativeElement.querySelector('code').innerHTML;
 
-    it('should format a one-line code sample', async () => {
+    it('should format a one-line code sample without linenums by default', () => {
       hostComponent.setCode(oneLineCode);
-      await untilCodeFormatted();
-
-      // 'pln' spans are a tell-tale for syntax highlighting
-      const spans = fixture.nativeElement.querySelectorAll('span.pln');
-      expect(spans.length).toBeGreaterThan(0, 'formatted spans');
+      expect(getFormattedCode()).toBe(
+          `Formatted code (language: auto, linenums: false): ${oneLineCode}`);
     });
 
-    it('should format a one-line code sample without linenums by default', async () => {
+    it('should add line numbers to one-line code sample when linenums is `true`', () => {
       hostComponent.setCode(oneLineCode);
-      expect(await hasLineNumbers()).toBe(false);
+      hostComponent.linenums = true;
+      fixture.detectChanges();
+
+      expect(getFormattedCode()).toBe(
+          `Formatted code (language: auto, linenums: true): ${oneLineCode}`);
     });
 
-    it('should add line numbers to one-line code sample when linenums set true', async () => {
+    it('should add line numbers to one-line code sample when linenums is `\'true\'`', () => {
+      hostComponent.setCode(oneLineCode);
       hostComponent.linenums = 'true';
       fixture.detectChanges();
 
-      expect(await hasLineNumbers()).toBe(true);
+      expect(getFormattedCode()).toBe(
+          `Formatted code (language: auto, linenums: true): ${oneLineCode}`);
     });
 
     it('should format a small multi-line code without linenums by default', async () => {
       hostComponent.setCode(smallMultiLineCode);
-      expect(await hasLineNumbers()).toBe(false);
+      expect(getFormattedCode()).toBe(
+          `Formatted code (language: auto, linenums: false): ${smallMultiLineCode}`);
     });
 
     it('should add line numbers to a big multi-line code by default', async () => {
       hostComponent.setCode(bigMultiLineCode);
-      expect(await hasLineNumbers()).toBe(true);
+      expect(getFormattedCode()).toBe(
+          `Formatted code (language: auto, linenums: true): ${bigMultiLineCode}`);
     });
 
-    it('should format big multi-line code without linenums when linenums set false', async () => {
+    it('should format big multi-line code without linenums when linenums is `false`', async () => {
+      hostComponent.setCode(bigMultiLineCode);
       hostComponent.linenums = false;
       fixture.detectChanges();
 
+      expect(getFormattedCode()).toBe(
+          `Formatted code (language: auto, linenums: false): ${bigMultiLineCode}`);
+    });
+
+    it('should format big multi-line code without linenums when linenums is `\'false\'`', async () => {
       hostComponent.setCode(bigMultiLineCode);
-      expect(await hasLineNumbers()).toBe(false);
+      hostComponent.linenums = 'false';
+      fixture.detectChanges();
+
+      expect(getFormattedCode()).toBe(
+          `Formatted code (language: auto, linenums: false): ${bigMultiLineCode}`);
     });
   });
 
@@ -117,9 +107,16 @@ describe('CodeComponent', () => {
       hostComponent.linenums = false;
       fixture.detectChanges();
 
-      hostComponent.setCode('  abc\n   let x = text.split(\'\\n\');\n  ghi\n\n  jkl\n');
+      hostComponent.setCode(`
+        abc
+          let x = text.split('\\n');
+        ghi
+
+        jkl
+      `);
       const codeContent = fixture.nativeElement.querySelector('code').textContent;
-      expect(codeContent).toEqual('abc\n let x = text.split(\'\\n\');\nghi\n\njkl');
+      expect(codeContent).toEqual(
+          'Formatted code (language: auto, linenums: false): abc\n  let x = text.split(\'\\n\');\nghi\n\njkl');
     });
 
     it('should trim whitespace from the code before rendering', () => {

aio/src/app/documents/document.service.spec.ts

@@ -47,6 +47,7 @@ describe('DocumentService', () => {
       docService.currentDocument.subscribe();
 
       httpMock.expectOne(CONTENT_URL_PREFIX + 'initial/doc.json');
+      expect().nothing();  // Prevent jasmine from complaining about no expectations.
     });
 
     it('should emit a document each time the location changes', () => {
@@ -185,6 +186,7 @@ describe('DocumentService', () => {
       docService.currentDocument.subscribe();
 
       httpMock.expectOne(CONTENT_URL_PREFIX + 'index.json');
+      expect().nothing();  // Prevent jasmine from complaining about no expectations.
     });
 
     it('should map the "folder" locations to the correct document request', () => {
@@ -192,6 +194,7 @@ describe('DocumentService', () => {
       docService.currentDocument.subscribe();
 
       httpMock.expectOne(CONTENT_URL_PREFIX + 'guide.json');
+      expect().nothing();  // Prevent jasmine from complaining about no expectations.
     });
   });
 });

aio/src/app/layout/mode-banner/mode-banner.component.ts

@@ -4,9 +4,9 @@ import { VersionInfo } from 'app/navigation/navigation.service';
 @Component({
   selector: 'aio-mode-banner',
   template: `
-  <div *ngIf="mode == 'archive'" class="mode-banner">
-    This is the <strong>archived documentation for Angular v{{version?.major}}.</strong>
-    Please visit <a href="https://angular.io/">angular.io</a> to see documentation for the current version of Angular.
+  <div *ngIf="mode == 'archive'" class="mode-banner alert archive-warning">
+    <p>This is the <strong>archived documentation for Angular v{{version?.major}}.</strong>
+    Please visit <a href="https://angular.io/">angular.io</a> to see documentation for the current version of Angular.</p>
   </div>
   `
 })

aio/src/app/shared/scroll.service.spec.ts

@@ -51,6 +51,8 @@ describe('ScrollService', () => {
     spyOn(window, 'scrollBy');
   });
 
+  afterEach(() => scrollService.ngOnDestroy());
+
   it('should debounce `updateScrollPositonInHistory()`', fakeAsync(() => {
     const updateScrollPositionInHistorySpy = spyOn(scrollService, 'updateScrollPositionInHistory');
 
@@ -65,6 +67,25 @@ describe('ScrollService', () => {
     expect(updateScrollPositionInHistorySpy).toHaveBeenCalledTimes(1);
   }));
 
+  it('should stop updating scroll position once destroyed', fakeAsync(() => {
+    const updateScrollPositionInHistorySpy = spyOn(scrollService, 'updateScrollPositionInHistory');
+
+    window.dispatchEvent(new Event('scroll'));
+    tick(250);
+    expect(updateScrollPositionInHistorySpy).toHaveBeenCalledTimes(1);
+
+    window.dispatchEvent(new Event('scroll'));
+    tick(250);
+    expect(updateScrollPositionInHistorySpy).toHaveBeenCalledTimes(2);
+
+    updateScrollPositionInHistorySpy.calls.reset();
+    scrollService.ngOnDestroy();
+
+    window.dispatchEvent(new Event('scroll'));
+    tick(250);
+    expect(updateScrollPositionInHistorySpy).not.toHaveBeenCalled();
+  }));
+
   it('should set `scrollRestoration` to `manual` if supported', () => {
     if (scrollService.supportManualScrollRestoration) {
       expect(window.history.scrollRestoration).toBe('manual');
@@ -112,6 +133,23 @@ describe('ScrollService', () => {
       expect(scrollService.topOffset).toBe(100 + topMargin);
       expect(document.querySelector).toHaveBeenCalled();
     });
+
+    it('should stop updating on resize once destroyed', () => {
+      let clientHeight = 50;
+      (document.querySelector as jasmine.Spy).and.callFake(() => ({clientHeight}));
+
+      expect(scrollService.topOffset).toBe(50 + topMargin);
+
+      clientHeight = 100;
+      window.dispatchEvent(new Event('resize'));
+      expect(scrollService.topOffset).toBe(100 + topMargin);
+
+      scrollService.ngOnDestroy();
+
+      clientHeight = 200;
+      window.dispatchEvent(new Event('resize'));
+      expect(scrollService.topOffset).toBe(100 + topMargin);
+    });
   });
 
   describe('#topOfPageElement', () => {

aio/src/app/shared/scroll.service.ts

@@ -1,7 +1,7 @@
 import { DOCUMENT, Location, PlatformLocation, PopStateEvent, ViewportScroller } from '@angular/common';
-import { Injectable, Inject } from '@angular/core';
-import { fromEvent } from 'rxjs';
-import { debounceTime } from 'rxjs/operators';
+import { Injectable, Inject, OnDestroy } from '@angular/core';
+import { fromEvent, Subject } from 'rxjs';
+import { debounceTime, takeUntil } from 'rxjs/operators';
 
 type ScrollPosition = [number, number];
 interface ScrollPositionPopStateEvent extends PopStateEvent {
@@ -14,10 +14,11 @@ export const topMargin = 16;
  * A service that scrolls document elements into view
  */
 @Injectable()
-export class ScrollService {
+export class ScrollService implements OnDestroy {
 
   private _topOffset: number | null;
   private _topOfPageElement: Element;
+  private onDestroy = new Subject<void>();
 
   // The scroll position which has to be restored, after a `popstate` event.
   poppedStateScrollPosition: ScrollPosition | null = null;
@@ -49,10 +50,13 @@ export class ScrollService {
       private viewportScroller: ViewportScroller,
       private location: Location) {
     // On resize, the toolbar might change height, so "invalidate" the top offset.
-    fromEvent(window, 'resize').subscribe(() => this._topOffset = null);
+    fromEvent(window, 'resize')
+        .pipe(takeUntil(this.onDestroy))
+        .subscribe(() => this._topOffset = null);
 
     fromEvent(window, 'scroll')
-      .pipe(debounceTime(250)).subscribe(() => this.updateScrollPositionInHistory());
+        .pipe(debounceTime(250), takeUntil(this.onDestroy))
+        .subscribe(() => this.updateScrollPositionInHistory());
 
     // Change scroll restoration strategy to `manual` if it's supported
     if (this.supportManualScrollRestoration) {
@@ -75,6 +79,10 @@ export class ScrollService {
     }
   }
 
+  ngOnDestroy() {
+    this.onDestroy.next();
+  }
+
   /**
    * Scroll to the element with id extracted from the current location hash fragment.
    * Scroll to top if no hash.

aio/src/app/shared/search-results/search-results.component.html

@@ -26,5 +26,5 @@
 </ng-template>
 
 <ng-template #notFound>
-  <p>{{notFoundMessage}}</p>
+  <p class="not-found">{{notFoundMessage}}</p>
 </ng-template>

aio/src/app/shared/select/select.component.html

@@ -1,6 +1,6 @@
 <div class="form-select-menu">
   <button class="form-select-button" (click)="toggleOptions()" [disabled]="disabled">
-    <strong>{{label}}</strong><span *ngIf="showSymbol" class="symbol {{selected?.value}}"></span>{{selected?.title}}
+    <span><strong>{{label}}</strong></span><span *ngIf="showSymbol" class="symbol {{selected?.value}}"></span><span>{{selected?.title}}</span>
   </button>
   <ul class="form-select-dropdown" *ngIf="showOptions">
     <li *ngFor="let option of options; index as i"
@@ -10,7 +10,7 @@
         (click)="select(option, i)"
         (keydown.enter)="select(option, i)"
         (keydown.space)="select(option, i); $event.preventDefault()">
-      <span *ngIf="showSymbol" class="symbol {{option.value}}"></span>{{option.title}}
+      <span *ngIf="showSymbol" class="symbol {{option.value}}"></span><span>{{option.title}}</span>
     </li>
   </ul>
 </div>

aio/src/app/shared/select/select.component.spec.ts

@@ -41,13 +41,11 @@ describe('SelectComponent', () => {
       expect(getButton().textContent!.trim()).toEqual('Label:');
     });
 
-    it('should contain a symbol `<span>` if hasSymbol is true', () => {
-      expect(getButton().querySelector('span')).toEqual(null);
+    it('should contain a symbol if hasSymbol is true', () => {
+      expect(getButtonSymbol()).toEqual(null);
       host.showSymbol = true;
       fixture.detectChanges();
-      const span = getButton().querySelector('span');
-      expect(span).not.toEqual(null);
-      expect(span!.className).toContain('symbol');
+      expect(getButtonSymbol()).not.toEqual(null);
     });
 
     it('should display the selected option, if there is one', () => {
@@ -55,7 +53,7 @@ describe('SelectComponent', () => {
       host.selected = options[0];
       fixture.detectChanges();
       expect(getButton().textContent).toContain(options[0].title);
-      expect(getButton().querySelector('span')!.className).toContain(options[0].value);
+      expect(getButtonSymbol()!.className).toContain(options[0].value);
     });
 
     it('should toggle the visibility of the options list when clicked', () => {
@@ -110,7 +108,7 @@ describe('SelectComponent', () => {
       fixture.detectChanges();
       expect(host.onChange).toHaveBeenCalledWith({ option: options[0], index: 0 });
       expect(getButton().textContent).toContain(options[0].title);
-      expect(getButton().querySelector('span')!.className).toContain(options[0].value);
+      expect(getButtonSymbol()!.className).toContain(options[0].value);
     });
 
     it('should select the current option when enter is pressed', () => {
@@ -119,7 +117,7 @@ describe('SelectComponent', () => {
       fixture.detectChanges();
       expect(host.onChange).toHaveBeenCalledWith({ option: options[0], index: 0 });
       expect(getButton().textContent).toContain(options[0].title);
-      expect(getButton().querySelector('span')!.className).toContain(options[0].value);
+      expect(getButtonSymbol()!.className).toContain(options[0].value);
     });
 
     it('should select the current option when space is pressed', () => {
@@ -128,7 +126,7 @@ describe('SelectComponent', () => {
       fixture.detectChanges();
       expect(host.onChange).toHaveBeenCalledWith({ option: options[0], index: 0 });
       expect(getButton().textContent).toContain(options[0].title);
-      expect(getButton().querySelector('span')!.className).toContain(options[0].value);
+      expect(getButtonSymbol()!.className).toContain(options[0].value);
     });
 
     it('should hide when an option is clicked', () => {
@@ -177,6 +175,10 @@ function getButton(): HTMLButtonElement {
   return element.query(By.css('button')).nativeElement;
 }
 
+function getButtonSymbol(): HTMLElement | null {
+  return getButton().querySelector('.symbol');
+}
+
 function getOptionContainer(): HTMLUListElement|null {
   const de = element.query(By.css('ul'));
   return de && de.nativeElement;

aio/src/styles/1-layouts/_content-layout.scss

@@ -1,33 +1,35 @@
-aio-shell.page-docs {
-  .sidenav-content {
-    // padding: 6rem 3rem 3rem 3rem; // THIS CAUSES THE TOP NAV TOOLBAR TO JUMP BETWEEN DOCS AND OTHER PAGES
-    margin: auto;
-  }
-}
-
-.sidenav-content {
-  min-height: 100vh;
-  padding: 80px 3rem 2rem;
-}
-
-@media (max-width: 600px) {
-  aio-menu {
-    display: none;
-  }
-
-  .sidenav-content {
-    min-height: 450px;
-    padding: 80px 1rem 1rem;
-  }
-}
-
 .sidenav-container {
   width: 100%;
   height: 100vh;
 }
 
-.sidenav-content button {
-  min-width: 24px;
+.sidenav-content {
+  min-height: 100vh;
+  padding: 80px 3rem 2rem;
+
+  @media screen and (max-width: 600px) {
+    min-height: 450px;
+    padding: 80px 2rem 1rem;
+  }
+
+  @media screen and (max-width: 480px) {
+    padding: 80px 1rem 1rem;
+  }
+
+  aio-shell.page-docs & {
+    // padding: 6rem 3rem 3rem 3rem; // THIS CAUSES THE TOP NAV TOOLBAR TO JUMP BETWEEN DOCS AND OTHER PAGES
+    margin: auto;
+  }
+
+  button {
+    min-width: 24px;
+  }
+}
+
+aio-menu {
+  @media (max-width: 600px) {
+    display: none;
+  }
 }
 
 #guide-change-log h2::before {

aio/src/styles/1-layouts/_layout-global.scss

@@ -7,6 +7,10 @@ body,
     background-color: $white;
 }
 
+.github-links + .content h1 {
+  max-width: 90%;
+}
+
 .clearfix {
     content: "";
     display: table;

aio/src/styles/1-layouts/_marketing-layout.scss

@@ -246,12 +246,7 @@ section#intro {
 }
 
 .button.hero-cta {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 184px;
-  height: 40px;
-  padding: 0 24px;
+  padding: 2px 34px 0;
   @include font-size(18);
   font-weight: 600;
   @include line-height(40);

aio/src/styles/1-layouts/_not-found.scss

@@ -1,7 +1,3 @@
-#file-not-found {
-    padding: 3rem 3rem 3rem;
-}
-
 .nf-container {
     align-items: center;
     padding: 32px;