release: cut the v10.1.5 release

Decorator API pages list all their available options in an overview
table and also in a detailed view. Now the rendered syntax of each
option will show a `?` after the name if the option is not required.
This is inline with how class and interface members are rendered.

PR Close #39167

.bazelversion

@@ -1,3 +1,3 @@
-3.2.0
+3.5.1
 # [NB: this comment has to be after the first line, see https://github.com/bazelbuild/bazelisk/issues/117]
 # When updating the Bazel version you also need to update the RBE toolchains version in package.bzl

.circleci/bazel.linux.rc

@@ -14,8 +14,8 @@ build --repository_cache=/home/circleci/bazel_repository_cache
 # Bazel doesn't calculate the memory ceiling correctly when running under Docker.
 # Limit Bazel to consuming resources that fit in CircleCI "xlarge" class
 # https://circleci.com/docs/2.0/configuration-reference/#resource_class
-build --local_cpu_resources=8
-build --local_ram_resources=14336
+build --local_cpu_resources=20
+build --local_ram_resources=32768
 
 # All build executed remotely should be done using our RBE configuration.
 build:remote --google_default_credentials

.circleci/bazel.windows.rc

@@ -11,8 +11,8 @@ try-import %workspace%/.circleci/bazel.common.rc
 build --repository_cache=C:/Users/circleci/bazel_repository_cache
 
 # Manually set the local resources used in windows CI runs
-build --local_ram_resources=13500
-build --local_cpu_resources=4
+build --local_ram_resources=120000
+build --local_cpu_resources=32
 
 # All windows jobs run on master and should use http caching
 build --remote_http_cache=https://storage.googleapis.com/angular-team-cache

.circleci/config.yml

@@ -80,7 +80,7 @@ executors:
 
   windows-executor:
     working_directory: ~/ng
-    resource_class: windows.medium
+    resource_class: windows.2xlarge
     # CircleCI windows VMs do have the GitBash shell available:
     # https://github.com/CircleCI-Public/windows-preview-docs#shells
     # But in this specific case we really should not use it because Bazel must not be ran from
@@ -273,6 +273,7 @@ jobs:
       - run: yarn -s ng-dev format changed $CI_GIT_BASE_REVISION --check
       - run: yarn -s ts-circular-deps:check
       - run: yarn -s ng-dev pullapprove verify
+      - run: yarn -s ng-dev ngbot verify
       - run: yarn -s ng-dev commit-message validate-range --range $CI_COMMIT_RANGE
 
   test:

.circleci/windows-env.ps1

@@ -41,7 +41,8 @@ copy .circleci\bazel.windows.rc ${Env:USERPROFILE}\.bazelrc
 ####################################################################################################
 # Install specific version of node.
 ####################################################################################################
-choco install nodejs --version 12.14.1 --no-progress
+nvm install 12.14.1
+nvm use 12.14.1
 
 # These Bazel prereqs aren't needed because the CircleCI image already includes them.
 # choco install yarn --version 1.16.0 --no-progress

.github/angular-robot.yml

@@ -38,6 +38,7 @@ merge:
       - "modules/benchmarks/**"
       - "modules/system.d.ts"
       - "packages/**"
+      - "dev-infra/benchmark/driver-utilities/**"
     # list of patterns to ignore for the files changed by the PR
     exclude:
       - "packages/*"
@@ -47,7 +48,10 @@ merge:
       - "packages/bazel/src/ng_package/**"
       - "packages/bazel/src/protractor/**"
       - "packages/bazel/src/schematics/**"
+      - "packages/compiler-cli/src/ngcc/**"
+      - "packages/compiler-cli/linker/**"
       - "packages/compiler-cli/ngcc/**"
+      - "packages/compiler-cli/src/ngtsc/sourcemaps/**"
       - "packages/docs/**"
       - "packages/elements/schematics/**"
       - "packages/examples/**"
@@ -55,6 +59,8 @@ merge:
       - "packages/localize/**"
       - "packages/private/**"
       - "packages/service-worker/**"
+      - "packages/common/locales/**"
+      - "packages/http/**"
       - "**/.gitignore"
       - "**/.gitkeep"
       - "**/yarn.lock"
@@ -68,6 +74,7 @@ merge:
       - "packages/**/integrationtest/**"
       - "packages/**/test/**"
       - "packages/zone.js/*"
+      - "packages/zone.js/dist/**"
       - "packages/zone.js/doc/**"
       - "packages/zone.js/example/**"
       - "packages/zone.js/scripts/**"
@@ -135,24 +142,28 @@ triage:
   # arrays of labels that determine if an issue has been fully triaged
   l2TriageLabels:
     -
-      - "type: bug/fix"
-      - "severity*"
-      - "freq*"
+      - "P0"
       - "comp: *"
     -
-      - "type: feature"
+      - "P1"
       - "comp: *"
     -
-      - "type: refactor"
+      - "P2"
       - "comp: *"
     -
-      - "type: RFC / Discussion / question"
+      - "P3"
       - "comp: *"
     -
-      - "type: confusing"
+      - "P4"
       - "comp: *"
     -
-      - "type: use-case"
+      - "P5"
+      - "comp: *"
+    -
+      - "feature"
+      - "comp: *"
+    -
+      - "discussion"
       - "comp: *"
 
 # options for the triage PR plugin

.ng-dev/caretaker.ts

@@ -12,7 +12,7 @@ export const caretaker: CaretakerConfig = {
       query: `is:pr is:open status:success label:"action: merge-assistance"`,
     },
     {
-      name: 'Primary Triage Queue',
+      name: 'Initial Triage Queue',
       query: `is:open is:issue no:milestone`,
     }
   ]

.ng-dev/config.ts

@@ -3,6 +3,7 @@ import {commitMessage} from './commit-message';
 import {format} from './format';
 import {github} from './github';
 import {merge} from './merge';
+import {release} from './release';
 
 module.exports = {
   commitMessage,
@@ -10,4 +11,5 @@ module.exports = {
   github,
   merge,
   caretaker,
+  release,
 };

.ng-dev/merge.ts

@@ -1,6 +1,7 @@
 import {DevInfraMergeConfig} from '../dev-infra/pr/merge/config';
 import {getDefaultTargetLabelConfiguration} from '../dev-infra/pr/merge/defaults';
 import {github} from './github';
+import {release} from './release';
 
 /**
  * Configuration for the merge tool in `ng-dev`. This sets up the labels which
@@ -13,7 +14,9 @@ export const merge: DevInfraMergeConfig['merge'] = async api => {
     mergeReadyLabel: /^action: merge(-assistance)?/,
     caretakerNoteLabel: 'action: merge-assistance',
     commitMessageFixupLabel: 'commit message fixup',
-    labels: await getDefaultTargetLabelConfiguration(api, github, '@angular/core'),
+    // We can pick any of the NPM packages as we are in a monorepo where all packages are
+    // published together with the same version and branching.
+    labels: await getDefaultTargetLabelConfiguration(api, github, release),
     requiredBaseCommits: {
       // PRs that target either `master` or the patch branch, need to be rebased
       // on top of the latest commit message validation fix.

.ng-dev/release.ts

@@ -0,0 +1,33 @@
+import {join} from 'path';
+import {exec} from 'shelljs';
+import {ReleaseConfig} from '../dev-infra/release/config';
+
+/** Configuration for the `ng-dev release` command. */
+export const release: ReleaseConfig = {
+  npmPackages: [
+    '@angular/animations',
+    '@angular/bazel',
+    '@angular/common',
+    '@angular/compiler',
+    '@angular/compiler-cli',
+    '@angular/core',
+    '@angular/elements',
+    '@angular/forms',
+    '@angular/language-service',
+    '@angular/localize',
+    '@angular/platform-browser',
+    '@angular/platform-browser-dynamic',
+    '@angular/platform-server',
+    '@angular/platform-webworker',
+    '@angular/platform-webworker-dynamic',
+    '@angular/router',
+    '@angular/service-worker',
+    '@angular/upgrade',
+  ],
+  // TODO: Implement release package building here.
+  buildPackages: async () => [],
+  // TODO: This can be removed once there is a org-wide tool for changelog generation.
+  generateReleaseNotesForHead: async () => {
+    exec('yarn -s gulp changelog', {cwd: join(__dirname, '../')});
+  },
+};

.pullapprove.yml

@@ -284,7 +284,7 @@ groups:
       users:
         - alxhub
         - crisbeto
-        - devversion
+        # OOO as of 2020-09-28 - devversion
 
 
   # =========================================================
@@ -326,6 +326,7 @@ groups:
           'aio/content/examples/component-interaction/**',
           'aio/content/images/guide/component-interaction/**',
           'aio/content/guide/component-styles.md',
+          'aio/content/guide/view-encapsulation.md',
           'aio/content/examples/component-styles/**',
           'aio/content/guide/dependency-injection.md',
           'aio/content/examples/dependency-injection/**',
@@ -419,7 +420,7 @@ groups:
         - atscott
         - ~kara  # do not request reviews from Kara, but allow her to approve PRs
         - mhevery
-        - pkozlowski-opensource
+        # OOO as of 2020-09-28 - pkozlowski-opensource
 
 
   # =========================================================
@@ -662,7 +663,7 @@ groups:
       users:
         - AndrewKushnir
         - IgorMinar
-        - pkozlowski-opensource
+        # OOO as of 2020-09-28 - pkozlowski-opensource
 
 
   # =========================================================
@@ -679,7 +680,7 @@ groups:
     reviewers:
       users:
         - IgorMinar
-        - pkozlowski-opensource
+        # OOO as of 2020-09-28 - pkozlowski-opensource
 
 
   # =========================================================
@@ -697,7 +698,7 @@ groups:
       users:
         - IgorMinar
         - jelbourn
-        - pkozlowski-opensource
+        # OOO as of 2020-09-28 - pkozlowski-opensource
 
 
   # =========================================================
@@ -723,7 +724,7 @@ groups:
         - IgorMinar
         - mhevery
         - jelbourn
-        - pkozlowski-opensource
+        # OOO as of 2020-09-28 - pkozlowski-opensource
     reviews:
       request: -1   # request reviews from everyone
       required: 2   # require at least 2 approvals
@@ -1115,6 +1116,7 @@ groups:
           'docs/DEBUG.md',
           'docs/DEBUG_COMPONENTS_REPO_IVY.md',
           'docs/DEVELOPER.md',
+          'docs/FIXUP_COMMITS.md',
           'docs/GITHUB_PROCESS.md',
           'docs/PR_REVIEW.md',
           'docs/SAVED_REPLIES.md',
@@ -1150,7 +1152,7 @@ groups:
           ])
     reviewers:
       users:
-        - devversion
+        # OOO as of 2020-09-28 - devversion
         - filipesilva
         - gkalpak
         - IgorMinar
@@ -1184,7 +1186,7 @@ groups:
         - atscott
         - jelbourn
         - petebacondarwin
-        - pkozlowski-opensource
+        # OOO as of 2020-09-28 - pkozlowski-opensource
     reviews:
       request: 4 # Request reviews from four people
       required: 3 # Require that three people approve
@@ -1212,7 +1214,7 @@ groups:
         - atscott
         - jelbourn
         - petebacondarwin
-        - pkozlowski-opensource
+        # OOO as of 2020-09-28 - pkozlowski-opensource
     reviews:
       request: 4 # Request reviews from four people
       required: 2 # Require that two people approve
@@ -1240,7 +1242,7 @@ groups:
         - atscott
         - jelbourn
         - petebacondarwin
-        - pkozlowski-opensource
+        # OOO as of 2020-09-28 - pkozlowski-opensource
 
 
 ####################################################################################

.yarn/releases/yarn-1.22.5.js

@@ -44654,7 +44654,7 @@ const FOLDERS_IGNORE = [
 const DEFAULT_IGNORE = (0, (_filter || _load_filter()).ignoreLinesToRegex)([...FOLDERS_IGNORE,
 
 // ignore cruft
-'yarn.lock', '.lock-wscript', '.wafpickle-{0..9}', '*.swp', '._*', 'npm-debug.log', 'yarn-error.log', '.npmrc', '.yarnrc', '.npmignore', '.gitignore', '.DS_Store']);
+'yarn.lock', '.lock-wscript', '.wafpickle-{0..9}', '*.swp', '._*', 'npm-debug.log', 'yarn-error.log', '.npmrc', '.yarnrc', '.yarnrc.yml', '.npmignore', '.gitignore', '.DS_Store']);
 
 const NEVER_IGNORE = (0, (_filter || _load_filter()).ignoreLinesToRegex)([
 // never ignore these files
@@ -44663,6 +44663,7 @@ const NEVER_IGNORE = (0, (_filter || _load_filter()).ignoreLinesToRegex)([
 function packWithIgnoreAndHeaders(cwd, ignoreFunction, { mapHeader } = {}) {
   return tar.pack(cwd, {
     ignore: ignoreFunction,
+    sort: true,
     map: header => {
       const suffix = header.name === '.' ? '' : `/${header.name}`;
       header.name = `package${suffix}`;
@@ -46678,7 +46679,7 @@ function mkdirfix (name, opts, cb) {
 /* 194 */
 /***/ (function(module, exports) {
 
-module.exports = {"name":"yarn","installationMethod":"unknown","version":"1.22.4","license":"BSD-2-Clause","preferGlobal":true,"description":"📦🐈 Fast, reliable, and secure dependency management.","dependencies":{"@zkochan/cmd-shim":"^3.1.0","babel-runtime":"^6.26.0","bytes":"^3.0.0","camelcase":"^4.0.0","chalk":"^2.1.0","cli-table3":"^0.4.0","commander":"^2.9.0","death":"^1.0.0","debug":"^3.0.0","deep-equal":"^1.0.1","detect-indent":"^5.0.0","dnscache":"^1.0.1","glob":"^7.1.1","gunzip-maybe":"^1.4.0","hash-for-dep":"^1.2.3","imports-loader":"^0.8.0","ini":"^1.3.4","inquirer":"^6.2.0","invariant":"^2.2.0","is-builtin-module":"^2.0.0","is-ci":"^1.0.10","is-webpack-bundle":"^1.0.0","js-yaml":"^3.13.1","leven":"^2.0.0","loud-rejection":"^1.2.0","micromatch":"^2.3.11","mkdirp":"^0.5.1","node-emoji":"^1.6.1","normalize-url":"^2.0.0","npm-logical-tree":"^1.2.1","object-path":"^0.11.2","proper-lockfile":"^2.0.0","puka":"^1.0.0","read":"^1.0.7","request":"^2.87.0","request-capture-har":"^1.2.2","rimraf":"^2.5.0","semver":"^5.1.0","ssri":"^5.3.0","strip-ansi":"^4.0.0","strip-bom":"^3.0.0","tar-fs":"^1.16.0","tar-stream":"^1.6.1","uuid":"^3.0.1","v8-compile-cache":"^2.0.0","validate-npm-package-license":"^3.0.4","yn":"^2.0.0"},"devDependencies":{"babel-core":"^6.26.0","babel-eslint":"^7.2.3","babel-loader":"^6.2.5","babel-plugin-array-includes":"^2.0.3","babel-plugin-inline-import":"^3.0.0","babel-plugin-transform-builtin-extend":"^1.1.2","babel-plugin-transform-inline-imports-commonjs":"^1.0.0","babel-plugin-transform-runtime":"^6.4.3","babel-preset-env":"^1.6.0","babel-preset-flow":"^6.23.0","babel-preset-stage-0":"^6.0.0","babylon":"^6.5.0","commitizen":"^2.9.6","cz-conventional-changelog":"^2.0.0","eslint":"^4.3.0","eslint-config-fb-strict":"^22.0.0","eslint-plugin-babel":"^5.0.0","eslint-plugin-flowtype":"^2.35.0","eslint-plugin-jasmine":"^2.6.2","eslint-plugin-jest":"^21.0.0","eslint-plugin-jsx-a11y":"^6.0.2","eslint-plugin-prefer-object-spread":"^1.2.1","eslint-plugin-prettier":"^2.1.2","eslint-plugin-react":"^7.1.0","eslint-plugin-relay":"^0.0.28","eslint-plugin-yarn-internal":"file:scripts/eslint-rules","execa":"^0.11.0","fancy-log":"^1.3.2","flow-bin":"^0.66.0","git-release-notes":"^3.0.0","gulp":"^4.0.0","gulp-babel":"^7.0.0","gulp-if":"^2.0.1","gulp-newer":"^1.0.0","gulp-plumber":"^1.0.1","gulp-sourcemaps":"^2.2.0","jest":"^22.4.4","jsinspect":"^0.12.6","minimatch":"^3.0.4","mock-stdin":"^0.3.0","prettier":"^1.5.2","string-replace-loader":"^2.1.1","temp":"^0.8.3","webpack":"^2.1.0-beta.25","yargs":"^6.3.0"},"resolutions":{"sshpk":"^1.14.2"},"engines":{"node":">=4.0.0"},"repository":"yarnpkg/yarn","bin":{"yarn":"./bin/yarn.js","yarnpkg":"./bin/yarn.js"},"scripts":{"build":"gulp build","build-bundle":"node ./scripts/build-webpack.js","build-chocolatey":"powershell ./scripts/build-chocolatey.ps1","build-deb":"./scripts/build-deb.sh","build-dist":"bash ./scripts/build-dist.sh","build-win-installer":"scripts\\build-windows-installer.bat","changelog":"git-release-notes $(git describe --tags --abbrev=0 $(git describe --tags --abbrev=0)^)..$(git describe --tags --abbrev=0) scripts/changelog.md","dupe-check":"yarn jsinspect ./src","lint":"eslint . && flow check","pkg-tests":"yarn --cwd packages/pkg-tests jest yarn.test.js","prettier":"eslint src __tests__ --fix","release-branch":"./scripts/release-branch.sh","test":"yarn lint && yarn test-only","test-only":"node --max_old_space_size=4096 node_modules/jest/bin/jest.js --verbose","test-only-debug":"node --inspect-brk --max_old_space_size=4096 node_modules/jest/bin/jest.js --runInBand --verbose","test-coverage":"node --max_old_space_size=4096 node_modules/jest/bin/jest.js --coverage --verbose","watch":"gulp watch","commit":"git-cz"},"jest":{"collectCoverageFrom":["src/**/*.js"],"testEnvironment":"node","modulePathIgnorePatterns":["__tests__/fixtures/","packages/pkg-tests/pkg-tests-fixtures","dist/"],"testPathIgnorePatterns":["__tests__/(fixtures|__mocks__)/","updates/","_(temp|mock|install|init|helpers).js$","packages/pkg-tests"]},"config":{"commitizen":{"path":"./node_modules/cz-conventional-changelog"}}}
+module.exports = {"name":"yarn","installationMethod":"unknown","version":"1.22.5","license":"BSD-2-Clause","preferGlobal":true,"description":"📦🐈 Fast, reliable, and secure dependency management.","dependencies":{"@zkochan/cmd-shim":"^3.1.0","babel-runtime":"^6.26.0","bytes":"^3.0.0","camelcase":"^4.0.0","chalk":"^2.1.0","cli-table3":"^0.4.0","commander":"^2.9.0","death":"^1.0.0","debug":"^3.0.0","deep-equal":"^1.0.1","detect-indent":"^5.0.0","dnscache":"^1.0.1","glob":"^7.1.1","gunzip-maybe":"^1.4.0","hash-for-dep":"^1.2.3","imports-loader":"^0.8.0","ini":"^1.3.4","inquirer":"^6.2.0","invariant":"^2.2.0","is-builtin-module":"^2.0.0","is-ci":"^1.0.10","is-webpack-bundle":"^1.0.0","js-yaml":"^3.13.1","leven":"^2.0.0","loud-rejection":"^1.2.0","micromatch":"^2.3.11","mkdirp":"^0.5.1","node-emoji":"^1.6.1","normalize-url":"^2.0.0","npm-logical-tree":"^1.2.1","object-path":"^0.11.2","proper-lockfile":"^2.0.0","puka":"^1.0.0","read":"^1.0.7","request":"^2.87.0","request-capture-har":"^1.2.2","rimraf":"^2.5.0","semver":"^5.1.0","ssri":"^5.3.0","strip-ansi":"^4.0.0","strip-bom":"^3.0.0","tar-fs":"^1.16.0","tar-stream":"^1.6.1","uuid":"^3.0.1","v8-compile-cache":"^2.0.0","validate-npm-package-license":"^3.0.4","yn":"^2.0.0"},"devDependencies":{"babel-core":"^6.26.0","babel-eslint":"^7.2.3","babel-loader":"^6.2.5","babel-plugin-array-includes":"^2.0.3","babel-plugin-inline-import":"^3.0.0","babel-plugin-transform-builtin-extend":"^1.1.2","babel-plugin-transform-inline-imports-commonjs":"^1.0.0","babel-plugin-transform-runtime":"^6.4.3","babel-preset-env":"^1.6.0","babel-preset-flow":"^6.23.0","babel-preset-stage-0":"^6.0.0","babylon":"^6.5.0","commitizen":"^2.9.6","cz-conventional-changelog":"^2.0.0","eslint":"^4.3.0","eslint-config-fb-strict":"^22.0.0","eslint-plugin-babel":"^5.0.0","eslint-plugin-flowtype":"^2.35.0","eslint-plugin-jasmine":"^2.6.2","eslint-plugin-jest":"^21.0.0","eslint-plugin-jsx-a11y":"^6.0.2","eslint-plugin-prefer-object-spread":"^1.2.1","eslint-plugin-prettier":"^2.1.2","eslint-plugin-react":"^7.1.0","eslint-plugin-relay":"^0.0.28","eslint-plugin-yarn-internal":"file:scripts/eslint-rules","execa":"^0.11.0","fancy-log":"^1.3.2","flow-bin":"^0.66.0","git-release-notes":"^3.0.0","gulp":"^4.0.0","gulp-babel":"^7.0.0","gulp-if":"^2.0.1","gulp-newer":"^1.0.0","gulp-plumber":"^1.0.1","gulp-sourcemaps":"^2.2.0","jest":"^22.4.4","jsinspect":"^0.12.6","minimatch":"^3.0.4","mock-stdin":"^0.3.0","prettier":"^1.5.2","string-replace-loader":"^2.1.1","temp":"^0.8.3","webpack":"^2.1.0-beta.25","yargs":"^6.3.0"},"resolutions":{"sshpk":"^1.14.2"},"engines":{"node":">=4.0.0"},"repository":"yarnpkg/yarn","bin":{"yarn":"./bin/yarn.js","yarnpkg":"./bin/yarn.js"},"scripts":{"build":"gulp build","build-bundle":"node ./scripts/build-webpack.js","build-chocolatey":"powershell ./scripts/build-chocolatey.ps1","build-deb":"./scripts/build-deb.sh","build-dist":"bash ./scripts/build-dist.sh","build-win-installer":"scripts\\build-windows-installer.bat","changelog":"git-release-notes $(git describe --tags --abbrev=0 $(git describe --tags --abbrev=0)^)..$(git describe --tags --abbrev=0) scripts/changelog.md","dupe-check":"yarn jsinspect ./src","lint":"eslint . && flow check","pkg-tests":"yarn --cwd packages/pkg-tests jest yarn.test.js","prettier":"eslint src __tests__ --fix","release-branch":"./scripts/release-branch.sh","test":"yarn lint && yarn test-only","test-only":"node --max_old_space_size=4096 node_modules/jest/bin/jest.js --verbose","test-only-debug":"node --inspect-brk --max_old_space_size=4096 node_modules/jest/bin/jest.js --runInBand --verbose","test-coverage":"node --max_old_space_size=4096 node_modules/jest/bin/jest.js --coverage --verbose","watch":"gulp watch","commit":"git-cz"},"jest":{"collectCoverageFrom":["src/**/*.js"],"testEnvironment":"node","modulePathIgnorePatterns":["__tests__/fixtures/","packages/pkg-tests/pkg-tests-fixtures","dist/"],"testPathIgnorePatterns":["__tests__/(fixtures|__mocks__)/","updates/","_(temp|mock|install|init|helpers).js$","packages/pkg-tests"]},"config":{"commitizen":{"path":"./node_modules/cz-conventional-changelog"}}}
 
 /***/ }),
 /* 195 */
@@ -98338,7 +98339,7 @@ var _buildSubCommands = (0, (_buildSubCommands2 || _load_buildSubCommands()).def
 
       const bundle = yield fetchBundle(config, bundleUrl);
 
-      const yarnPath = path.resolve(config.lockfileFolder, `.yarn/releases/yarn-${bundleVersion}.js`);
+      const yarnPath = path.resolve(config.lockfileFolder, `.yarn/releases/yarn-${bundleVersion}.cjs`);
       reporter.log(`Saving it into ${chalk.magenta(yarnPath)}...`);
       yield (_fs || _load_fs()).mkdirp(path.dirname(yarnPath));
       yield (_fs || _load_fs()).writeFile(yarnPath, bundle);
@@ -100190,7 +100191,7 @@ let main = exports.main = (() => {
 
     const config = new (_config || _load_config()).default(reporter);
     const outputWrapperEnabled = (0, (_conversion || _load_conversion()).boolifyWithDefault)(process.env.YARN_WRAP_OUTPUT, true);
-    const shouldWrapOutput = outputWrapperEnabled && !(_commander || _load_commander()).default.json && command.hasWrapper((_commander || _load_commander()).default, (_commander || _load_commander()).default.args);
+    const shouldWrapOutput = outputWrapperEnabled && !(_commander || _load_commander()).default.json && command.hasWrapper((_commander || _load_commander()).default, (_commander || _load_commander()).default.args) && !(commandName === 'init' && (_commander || _load_commander()).default[`2`]);
 
     if (shouldWrapOutput) {
       reporter.header(commandName, { name: 'yarn', version: (_yarnVersion || _load_yarnVersion()).version });
@@ -100604,7 +100605,7 @@ let start = (() => {
       });
 
       try {
-        if (yarnPath.endsWith(`.js`)) {
+        if (/\.[cm]?js$/.test(yarnPath)) {
           exitCode = yield (0, (_child || _load_child()).spawnp)(process.execPath, [yarnPath, ...argv], opts);
         } else {
           exitCode = yield (0, (_child || _load_child()).spawnp)(yarnPath, argv, opts);

.yarnrc

@@ -2,4 +2,4 @@
 # yarn lockfile v1
 
 
-yarn-path ".yarn/releases/yarn-1.22.4.js"
+yarn-path ".yarn/releases/yarn-1.22.5.js"

BUILD.bazel

@@ -34,7 +34,7 @@ filegroup(
 filegroup(
     name = "angularjs_scripts",
     srcs = [
-        # We also declare the unminfied AngularJS files since these can be used for
+        # We also declare the unminified 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",

CHANGELOG.md

@@ -1,3 +1,40 @@
+<a name="10.1.5"></a>
+## 10.1.5 (2020-10-07)
+
+
+### Bug Fixes
+
+* **router:** update getRouteGuards to check if the context outlet is activated ([#39049](https://github.com/angular/angular/issues/39049)) ([771f731](https://github.com/angular/angular/commit/771f731)), closes [#39030](https://github.com/angular/angular/issues/39030)
+* **compiler:** Recover on malformed keyed reads and keyed writes ([#39004](https://github.com/angular/angular/issues/39004)) ([f50313f](https://github.com/angular/angular/commit/f50313f)), closes [#38596](https://github.com/angular/angular/issues/38596)
+
+
+
+<a name="10.1.4"></a>
+## 10.1.4 (2020-09-30)
+
+
+### Bug Fixes
+
+* **compiler-cli:** enable [@types](https://github.com/types) discovery in incremental rebuilds ([#39011](https://github.com/angular/angular/issues/39011)) ([6e99427](https://github.com/angular/angular/commit/6e99427)), closes [#38979](https://github.com/angular/angular/issues/38979)
+
+
+
+<a name="10.1.3"></a>
+## 10.1.3 (2020-09-23)
+
+
+### Bug Fixes
+
+* **http:** Fix error message when we call jsonp without importing HttpClientJsonpModule ([#38756](https://github.com/angular/angular/issues/38756)) ([3902ec0](https://github.com/angular/angular/commit/3902ec0))
+* **ngcc:** fix compilation of `ChangeDetectorRef` in pipe constructors ([#38892](https://github.com/angular/angular/issues/38892)) ([093c3a1](https://github.com/angular/angular/commit/093c3a1)), closes [#38666](https://github.com/angular/angular/issues/38666) [#38883](https://github.com/angular/angular/issues/38883)
+
+
+### Reverts
+
+* feat(router): better warning message when a router outlet has not been instantiated ([#38920](https://github.com/angular/angular/issues/38920)) ([04d0aa6](https://github.com/angular/angular/commit/04d0aa6))
+
+
+
 <a name="10.1.2"></a>
 ## 10.1.2 (2020-09-16)
 

CONTRIBUTING.md

@@ -107,7 +107,7 @@ Before you submit your Pull Request (PR) consider the following guidelines:
    Adherence to these conventions is necessary because release notes are automatically generated from these messages.
 
      ```shell
-     git commit -a
+     git commit --all
      ```
     Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files.
 
@@ -119,16 +119,31 @@ Before you submit your Pull Request (PR) consider the following guidelines:
 
 11. In GitHub, send a pull request to `angular:master`.
 
-   If we ask for changes via code reviews then:
 
-   * Make the required updates.
-   * Re-run the Angular test suites to ensure tests are still passing.
-   * Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
+#### Addressing review feedback
 
-      ```shell
-      git rebase master -i
-      git push -f
-      ```
+If we ask for changes via code reviews then:
+
+1. Make the required updates to the code.
+
+2. Re-run the Angular test suites to ensure tests are still passing.
+
+3. Create a fixup commit and push to your GitHub repository (this will update your Pull Request):
+
+    ```shell
+    git commit --all --fixup HEAD
+    git push
+    ```
+
+    For more info on working with fixup commits see [here](docs/FIXUP_COMMITS.md).
+
+> Fixup commits (as shown above) are preferred when addressing review feedback, but in some cases you may need to amend the original commit instead of creating a fixup commit (for example, if you want to update the commit message).
+> To amend the last commit and update the Pull Request:
+>
+> ```shell
+> git commit --all --amend
+> git push --force-with-lease
+> ```
 
 That's it! Thank you for your contribution!
 

WORKSPACE

@@ -91,8 +91,8 @@ rbe_autoconfig(
     # Need to specify a base container digest in order to ensure that we can use the checked-in
     # platform configurations for the "ubuntu16_04" image. Otherwise the autoconfig rule would
     # need to pull the image and run it in order determine the toolchain configuration. See:
-    # https://github.com/bazelbuild/bazel-toolchains/blob/3.2.0/configs/ubuntu16_04_clang/versions.bzl
-    base_container_digest = "sha256:5e750dd878df9fcf4e185c6f52b9826090f6e532b097f286913a428290622332",
+    # https://github.com/bazelbuild/bazel-toolchains/blob/3.5.1/configs/ubuntu16_04_clang/versions.bzl
+    base_container_digest = "sha256:f6568d8168b14aafd1b707019927a63c2d37113a03bcee188218f99bd0327ea1",
     # Note that if you change the `digest`, you might also need to update the
     # `base_container_digest` to make sure marketplace.gcr.io/google/rbe-ubuntu16-04-webtest:<digest>
     # and marketplace.gcr.io/google/rbe-ubuntu16-04:<base_container_digest> have

aio/README.md

@@ -6,6 +6,7 @@ Everything in this folder is part of the documentation project. This includes
 * the dgeni configuration for converting source files to rendered files that can be viewed in the web site.
 * the tooling for setting up examples for development; and generating live-example and zip files from the examples.
 
+<a name="developer-tasks"></a>
 ## Developer tasks
 
 We use [Yarn](https://yarnpkg.com) to manage the dependencies and to run build tasks.

aio/aio-builds-setup/docs/image-config--environment-variables.md

@@ -22,7 +22,7 @@ you don't need to specify values for those.
   The domain name of the server.
 
 - `AIO_GITHUB_ORGANIZATION`:
-  The GitHub organization whose teams are whitelisted for accepting build artifacts.
+  The GitHub organization whose teams are trusted for accepting build artifacts.
   See also `AIO_GITHUB_TEAM_SLUGS`.
 
 - `AIO_GITHUB_REPO`:

aio/aio-builds-setup/docs/overview--security-model.md

@@ -98,7 +98,7 @@ This section describes how each of the aforementioned sub-tasks is accomplished:
       Such a label can only have been added by a maintainer (with the necessary rights) and
       designates that they have manually verified the PR contents.
    2. We can verify (again using the GitHub API) the author's membership in one of the
-      whitelisted/trusted GitHub teams. For this operation, we need a Personal Access Token with the
+      trusted GitHub teams. For this operation, we need a Personal Access Token with the
       `read:org` scope issued by a user that can "see" the specified GitHub organization.
       Here too, we use the token by @mary-poppins.
 

aio/content/examples/.gitignore

@@ -17,6 +17,7 @@
 **/e2e/tsconfig.e2e.json
 **/src/karma.conf.js
 **/.angular-cli.json
+**/.browserslistrc
 **/.editorconfig
 **/.gitignore
 **/angular.json
@@ -30,7 +31,6 @@
 **/tslint.json
 **/karma-test-shim.js
 **/browser-test-shim.js
-**/browserslist
 **/node_modules
 
 # built files

aio/content/examples/bootstrapping/src/app/app.module.ts

@@ -21,11 +21,13 @@ import { ItemDirective } from './item.directive';
     ItemDirective
   ],
   // #enddocregion declarations
+  // #docregion imports
   imports: [
     BrowserModule,
     FormsModule,
     HttpClientModule
   ],
+  // #enddocregion imports
   providers: [],
   bootstrap: [AppComponent]
 })

aio/content/examples/component-interaction/e2e/src/app.e2e-spec.ts

@@ -1,12 +1,8 @@
-import { browser, element, by } from 'protractor';
+import { browser, by, element } from 'protractor';
 
 describe('Component Communication Cookbook Tests', () => {
 
-  // Note: '?e2e' which app can read to know it is running in protractor
-  // e.g. `if (!/e2e/.test(location.search)) { ...`
-  beforeAll(() => {
-    browser.get('?e2e');
-  });
+  beforeEach(() => browser.get(browser.baseUrl));
 
   describe('Parent-to-child communication', () => {
     // #docregion parent-to-child
@@ -15,7 +11,7 @@ describe('Component Communication Cookbook Tests', () => {
     const masterName = 'Master';
 
     it('should pass properties to children properly', () => {
-      const parent = element.all(by.tagName('app-hero-parent')).get(0);
+      const parent = element(by.tagName('app-hero-parent'));
       const heroes = parent.all(by.tagName('app-hero-child'));
 
       for (let i = 0; i < heroNames.length; i++) {
@@ -35,7 +31,7 @@ describe('Component Communication Cookbook Tests', () => {
     it('should display trimmed, non-empty names', () => {
       const nonEmptyNameIndex = 0;
       const nonEmptyName = '"Dr IQ"';
-      const parent = element.all(by.tagName('app-name-parent')).get(0);
+      const parent = element(by.tagName('app-name-parent'));
       const hero = parent.all(by.tagName('app-name-child')).get(nonEmptyNameIndex);
 
       const displayName = hero.element(by.tagName('h3')).getText();
@@ -45,7 +41,7 @@ describe('Component Communication Cookbook Tests', () => {
     it('should replace empty name with default name', () => {
       const emptyNameIndex = 1;
       const defaultName = '"<no name set>"';
-      const parent = element.all(by.tagName('app-name-parent')).get(0);
+      const parent = element(by.tagName('app-name-parent'));
       const hero = parent.all(by.tagName('app-name-child')).get(emptyNameIndex);
 
       const displayName = hero.element(by.tagName('h3')).getText();
@@ -70,38 +66,36 @@ describe('Component Communication Cookbook Tests', () => {
       expect(actual.logs.get(0).getText()).toBe(initialLog);
     });
 
-    it('should set expected values after clicking \'Minor\' twice', () => {
+    it('should set expected values after clicking \'Minor\' twice', async () => {
       const repoTag = element(by.tagName('app-version-parent'));
       const newMinorButton = repoTag.all(by.tagName('button')).get(0);
 
-      newMinorButton.click().then(() => {
-        newMinorButton.click().then(() => {
-          const actual = getActual();
+      await newMinorButton.click();
+      await newMinorButton.click();
 
-          const labelAfter2Minor = 'Version 1.25';
-          const logAfter2Minor = 'minor changed from 24 to 25';
+      const actual = getActual();
 
-          expect(actual.label).toBe(labelAfter2Minor);
-          expect(actual.count).toBe(3);
-          expect(actual.logs.get(2).getText()).toBe(logAfter2Minor);
-        });
-      });
+      const labelAfter2Minor = 'Version 1.25';
+      const logAfter2Minor = 'minor changed from 24 to 25';
+
+      expect(actual.label).toBe(labelAfter2Minor);
+      expect(actual.count).toBe(3);
+      expect(actual.logs.get(2).getText()).toBe(logAfter2Minor);
     });
 
-    it('should set expected values after clicking \'Major\' once', () => {
+    it('should set expected values after clicking \'Major\' once', async () => {
       const repoTag = element(by.tagName('app-version-parent'));
       const newMajorButton = repoTag.all(by.tagName('button')).get(1);
 
-      newMajorButton.click().then(() => {
-        const actual = getActual();
+      await newMajorButton.click();
+      const actual = getActual();
 
-        const labelAfterMajor = 'Version 2.0';
-        const logAfterMajor = 'major changed from 1 to 2, minor changed from 25 to 0';
+      const labelAfterMajor = 'Version 2.0';
+      const logAfterMajor = 'major changed from 1 to 2, minor changed from 23 to 0';
 
-        expect(actual.label).toBe(labelAfterMajor);
-        expect(actual.count).toBe(4);
-        expect(actual.logs.get(3).getText()).toBe(logAfterMajor);
-      });
+      expect(actual.label).toBe(labelAfterMajor);
+      expect(actual.count).toBe(2);
+      expect(actual.logs.get(1).getText()).toBe(logAfterMajor);
     });
 
     function getActual() {
@@ -118,110 +112,125 @@ describe('Component Communication Cookbook Tests', () => {
     }
     // ...
     // #enddocregion parent-to-child-onchanges
-
   });
 
   describe('Child-to-parent communication', () => {
     // #docregion child-to-parent
     // ...
     it('should not emit the event initially', () => {
-      const voteLabel = element(by.tagName('app-vote-taker'))
-        .element(by.tagName('h3')).getText();
-      expect(voteLabel).toBe('Agree: 0, Disagree: 0');
+      const voteLabel = element(by.tagName('app-vote-taker')).element(by.tagName('h3'));
+      expect(voteLabel.getText()).toBe('Agree: 0, Disagree: 0');
     });
 
-    it('should process Agree vote', () => {
+    it('should process Agree vote', async () => {
+      const voteLabel = element(by.tagName('app-vote-taker')).element(by.tagName('h3'));
       const agreeButton1 = element.all(by.tagName('app-voter')).get(0)
         .all(by.tagName('button')).get(0);
-      agreeButton1.click().then(() => {
-        const voteLabel = element(by.tagName('app-vote-taker'))
-          .element(by.tagName('h3')).getText();
-        expect(voteLabel).toBe('Agree: 1, Disagree: 0');
-      });
+
+      await agreeButton1.click();
+
+      expect(voteLabel.getText()).toBe('Agree: 1, Disagree: 0');
     });
 
-    it('should process Disagree vote', () => {
+    it('should process Disagree vote', async () => {
+      const voteLabel = element(by.tagName('app-vote-taker')).element(by.tagName('h3'));
       const agreeButton1 = element.all(by.tagName('app-voter')).get(1)
         .all(by.tagName('button')).get(1);
-      agreeButton1.click().then(() => {
-        const voteLabel = element(by.tagName('app-vote-taker'))
-          .element(by.tagName('h3')).getText();
-        expect(voteLabel).toBe('Agree: 1, Disagree: 1');
-      });
+
+      await agreeButton1.click();
+
+      expect(voteLabel.getText()).toBe('Agree: 0, Disagree: 1');
     });
     // ...
     // #enddocregion child-to-parent
   });
 
-  // Can't run timer tests in protractor because
-  // interaction w/ zones causes all tests to freeze & timeout.
-  xdescribe('Parent calls child via local var', () => {
-    countDownTimerTests('countdown-parent-lv');
+  describe('Parent calls child via local var', () => {
+    countDownTimerTests('app-countdown-parent-lv');
   });
 
-  xdescribe('Parent calls ViewChild', () => {
-    countDownTimerTests('countdown-parent-vc');
+  describe('Parent calls ViewChild', () => {
+    countDownTimerTests('app-countdown-parent-vc');
   });
 
   function countDownTimerTests(parentTag: string) {
     // #docregion countdown-timer-tests
     // ...
-    it('timer and parent seconds should match', () => {
+    // The tests trigger periodic asynchronous operations (via `setInterval()`), which will prevent
+    // the app from stabilizing. See https://angular.io/api/core/ApplicationRef#is-stable-examples
+    // for more details.
+    // To allow the tests to complete, we will disable automatically waiting for the Angular app to
+    // stabilize.
+    beforeEach(() => browser.waitForAngularEnabled(false));
+    afterEach(() => browser.waitForAngularEnabled(true));
+
+    it('timer and parent seconds should match', async () => {
       const parent = element(by.tagName(parentTag));
-      const message = parent.element(by.tagName('app-countdown-timer')).getText();
-      browser.sleep(10); // give `seconds` a chance to catchup with `message`
-      const seconds = parent.element(by.className('seconds')).getText();
-      expect(message).toContain(seconds);
+      const startButton = parent.element(by.buttonText('Start'));
+      const seconds = parent.element(by.className('seconds'));
+      const timer = parent.element(by.tagName('app-countdown-timer'));
+
+      await startButton.click();
+
+      // Wait for `<app-countdown-timer>` to be populated with any text.
+      await browser.wait(() => timer.getText(), 2000);
+
+      expect(await timer.getText()).toContain(await seconds.getText());
     });
 
-    it('should stop the countdown', () => {
+    it('should stop the countdown', async () => {
       const parent = element(by.tagName(parentTag));
-      const stopButton = parent.all(by.tagName('button')).get(1);
+      const startButton = parent.element(by.buttonText('Start'));
+      const stopButton = parent.element(by.buttonText('Stop'));
+      const timer = parent.element(by.tagName('app-countdown-timer'));
 
-      stopButton.click().then(() => {
-        const message = parent.element(by.tagName('app-countdown-timer')).getText();
-        expect(message).toContain('Holding');
-      });
+      await startButton.click();
+      expect(await timer.getText()).not.toContain('Holding');
+
+      await stopButton.click();
+      expect(await timer.getText()).toContain('Holding');
     });
     // ...
     // #enddocregion countdown-timer-tests
   }
 
-
   describe('Parent and children communicate via a service', () => {
     // #docregion bidirectional-service
     // ...
-    it('should announce a mission', () => {
+    it('should announce a mission', async () => {
       const missionControl = element(by.tagName('app-mission-control'));
       const announceButton = missionControl.all(by.tagName('button')).get(0);
-      announceButton.click().then(() => {
-        const history = missionControl.all(by.tagName('li'));
-        expect(history.count()).toBe(1);
-        expect(history.get(0).getText()).toMatch(/Mission.* announced/);
-      });
+      const history = missionControl.all(by.tagName('li'));
+
+      await announceButton.click();
+
+      expect(history.count()).toBe(1);
+      expect(history.get(0).getText()).toMatch(/Mission.* announced/);
     });
 
-    it('should confirm the mission by Lovell', () => {
-      testConfirmMission(1, 2, 'Lovell');
+    it('should confirm the mission by Lovell', async () => {
+      await testConfirmMission(1, 'Lovell');
     });
 
-    it('should confirm the mission by Haise', () => {
-      testConfirmMission(3, 3, 'Haise');
+    it('should confirm the mission by Haise', async () => {
+      await testConfirmMission(3, 'Haise');
     });
 
-    it('should confirm the mission by Swigert', () => {
-      testConfirmMission(2, 4, 'Swigert');
+    it('should confirm the mission by Swigert', async () => {
+      await testConfirmMission(2, 'Swigert');
     });
 
-    function testConfirmMission(buttonIndex: number, expectedLogCount: number, astronaut: string) {
-      const confirmedLog = ' confirmed the mission';
+    async function testConfirmMission(buttonIndex: number, astronaut: string) {
       const missionControl = element(by.tagName('app-mission-control'));
+      const announceButton = missionControl.all(by.tagName('button')).get(0);
       const confirmButton = missionControl.all(by.tagName('button')).get(buttonIndex);
-      confirmButton.click().then(() => {
-        const history = missionControl.all(by.tagName('li'));
-        expect(history.count()).toBe(expectedLogCount);
-        expect(history.get(expectedLogCount - 1).getText()).toBe(astronaut + confirmedLog);
-      });
+      const history = missionControl.all(by.tagName('li'));
+
+      await announceButton.click();
+      await confirmButton.click();
+
+      expect(history.count()).toBe(2);
+      expect(history.get(1).getText()).toBe(`${astronaut} confirmed the mission`);
     }
     // ...
     // #enddocregion bidirectional-service

aio/content/examples/component-interaction/example-config.json

@@ -1,13 +0,0 @@
-{
-  "tests": [
-    {
-      "cmd": "yarn",
-      "args": [
-        "e2e",
-        "--protractor-config=e2e/protractor-puppeteer.conf.js",
-        "--no-webdriver-update",
-        "--port={PORT}"
-      ]
-    }
-  ]
-}

aio/content/examples/component-interaction/src/app/app.component.html

@@ -30,22 +30,21 @@
   <app-vote-taker></app-vote-taker>
 </div>
 <a href="#top" class="to-top">Back to Top</a>
-<hr>
 
+<hr>
 <div id="parent-to-child-local-var">
   <app-countdown-parent-lv></app-countdown-parent-lv>
 </div>
 <a href="#top" class="to-top">Back to Top</a>
-<hr>
 
+<hr>
 <div id="parent-to-view-child">
   <app-countdown-parent-vc></app-countdown-parent-vc>
 </div>
 <a href="#top" class="to-top">Back to Top</a>
-<hr>
 
+<hr>
 <div id="bidirectional-service">
   <app-mission-control></app-mission-control>
 </div>
 <a href="#top" class="to-top">Back to Top</a>
-<hr>

aio/content/examples/component-interaction/src/app/app.module.ts

@@ -1,4 +1,4 @@
-import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+import { NgModule } from '@angular/core';
 import { BrowserModule } from '@angular/platform-browser';
 
 import { AppComponent } from './app.component';
@@ -15,10 +15,17 @@ import { VersionParentComponent } from './version-parent.component';
 import { VoterComponent } from './voter.component';
 import { VoteTakerComponent } from './votetaker.component';
 
-const directives: any[] = [
+
+@NgModule({
+  imports: [
+    BrowserModule,
+  ],
+  declarations: [
     AppComponent,
     AstronautComponent,
+    CountdownLocalVarParentComponent,
     CountdownTimerComponent,
+    CountdownViewChildParentComponent,
     HeroChildComponent,
     HeroParentComponent,
     MissionControlComponent,
@@ -27,28 +34,8 @@ const directives: any[] = [
     VersionChildComponent,
     VersionParentComponent,
     VoterComponent,
-    VoteTakerComponent
-  ];
-
-const schemas: any[] = [];
-
-// Include Countdown examples
-// unless in e2e tests which they break.
-if (!/e2e/.test(location.search)) {
-  console.log('adding countdown timer examples');
-  directives.push(CountdownLocalVarParentComponent);
-  directives.push(CountdownViewChildParentComponent);
-} else {
-  // In e2e test use CUSTOM_ELEMENTS_SCHEMA to suppress unknown element errors
-  schemas.push(CUSTOM_ELEMENTS_SCHEMA);
-}
-
-@NgModule({
-  imports: [
-    BrowserModule
+    VoteTakerComponent,
   ],
-  declarations: directives,
   bootstrap: [ AppComponent ],
-  schemas
 })
 export class AppModule { }

aio/content/examples/component-interaction/src/app/countdown-timer.component.ts

@@ -1,19 +1,16 @@
 // #docregion
-import { Component, OnDestroy, OnInit } from '@angular/core';
+import { Component, OnDestroy } from '@angular/core';
 
 @Component({
   selector: 'app-countdown-timer',
   template: '<p>{{message}}</p>'
 })
-export class CountdownTimerComponent implements OnInit, OnDestroy {
+export class CountdownTimerComponent implements OnDestroy {
 
   intervalId = 0;
   message = '';
   seconds = 11;
 
-  clearTimer() { clearInterval(this.intervalId); }
-
-  ngOnInit()    { this.start(); }
   ngOnDestroy() { this.clearTimer(); }
 
   start() { this.countDown(); }
@@ -22,6 +19,8 @@ export class CountdownTimerComponent implements OnInit, OnDestroy {
     this.message = `Holding at T-${this.seconds} seconds`;
   }
 
+  private clearTimer() { clearInterval(this.intervalId); }
+
   private countDown() {
     this.clearTimer();
     this.intervalId = window.setInterval(() => {

aio/content/examples/http/src/app/uploader/uploader.service.ts

@@ -24,7 +24,7 @@ export class UploaderService {
   // }
 
   upload(file: File) {
-    if (!file) { return; }
+    if (!file) { return of<string>(); }
 
     // COULD HAVE WRITTEN:
     // return this.http.post('/upload/file', file, {

aio/content/examples/observables-in-angular/src/main.ts

@@ -1,3 +1,4 @@
+// TODO: Add unit tests for this file.
 // tslint:disable: no-output-native
 // #docregion
 import { Component, Output, OnInit, EventEmitter, NgModule } from '@angular/core';

aio/content/examples/observables/example-config.json

@@ -2,7 +2,11 @@
   "tests": [
     {
       "cmd": "yarn",
-      "args": [ "tsc", "--project", "./tsconfig.app.json" ]
+      "args": ["tsc", "--project", "tsconfig.spec.json", "--module", "commonjs"]
+    },
+    {
+      "cmd": "yarn",
+      "args": ["jasmine", "out-tsc/**/*.spec.js"]
     }
   ]
 }

aio/content/examples/observables/src/creating.spec.ts

@@ -0,0 +1,55 @@
+import { docRegionFromEvent, docRegionSubscriber } from './creating';
+
+describe('observables', () => {
+  it('should create an observable using the constructor', () => {
+    const console = {log: jasmine.createSpy('log')};
+    docRegionSubscriber(console);
+    expect(console.log).toHaveBeenCalledTimes(4);
+    expect(console.log.calls.allArgs()).toEqual([
+      [1],
+      [2],
+      [3],
+      ['Finished sequence'],
+    ]);
+  });
+
+  it('should listen to input changes', () => {
+    let triggerInputChange;
+    const input = {
+      value: 'Test',
+      addEventListener: jasmine
+        .createSpy('addEvent')
+        .and.callFake((eventName: string, cb: (e) => void) => {
+          if (eventName === 'keydown') {
+            triggerInputChange = cb;
+          }
+        }),
+      removeEventListener: jasmine.createSpy('removeEventListener'),
+    };
+
+    const document = { getElementById: () => input };
+    docRegionFromEvent(document);
+    triggerInputChange({keyCode: 65});
+    expect(input.value).toBe('Test');
+
+    triggerInputChange({keyCode: 27});
+    expect(input.value).toBe('');
+  });
+
+  it('should call removeEventListener when unsubscribing', (doneFn: DoneFn) => {
+    const input = {
+      addEventListener: jasmine.createSpy('addEvent'),
+      removeEventListener: jasmine
+        .createSpy('removeEvent')
+        .and.callFake((eventName: string, cb: (e) => void) => {
+          if (eventName === 'keydown') {
+            doneFn();
+          }
+        })
+    };
+
+    const document = { getElementById: () => input };
+    const subscription = docRegionFromEvent(document);
+    subscription.unsubscribe();
+  });
+});

aio/content/examples/observables/src/creating.ts

@@ -1,38 +1,39 @@
+// #docplaster
 
 import { Observable } from 'rxjs';
 
-// #docregion subscriber
+export function docRegionSubscriber(console) {
+  // #docregion subscriber
+  // This function runs when subscribe() is called
+  function sequenceSubscriber(observer) {
+    // synchronously deliver 1, 2, and 3, then complete
+    observer.next(1);
+    observer.next(2);
+    observer.next(3);
+    observer.complete();
 
-// This function runs when subscribe() is called
-function sequenceSubscriber(observer) {
-  // synchronously deliver 1, 2, and 3, then complete
-  observer.next(1);
-  observer.next(2);
-  observer.next(3);
-  observer.complete();
+    // unsubscribe function doesn't need to do anything in this
+    // because values are delivered synchronously
+    return {unsubscribe() {}};
+  }
 
-  // unsubscribe function doesn't need to do anything in this
-  // because values are delivered synchronously
-  return {unsubscribe() {}};
+  // Create a new Observable that will deliver the above sequence
+  const sequence = new Observable(sequenceSubscriber);
+
+  // execute the Observable and print the result of each notification
+  sequence.subscribe({
+    next(num) { console.log(num); },
+    complete() { console.log('Finished sequence'); }
+  });
+
+  // Logs:
+  // 1
+  // 2
+  // 3
+  // Finished sequence
+  // #enddocregion subscriber
 }
 
-// Create a new Observable that will deliver the above sequence
-const sequence = new Observable(sequenceSubscriber);
-
-// execute the Observable and print the result of each notification
-sequence.subscribe({
-  next(num) { console.log(num); },
-  complete() { console.log('Finished sequence'); }
-});
-
-// Logs:
-// 1
-// 2
-// 3
-// Finished sequence
-
-// #enddocregion subscriber
-
 // #docregion fromevent
 
 function fromEvent(target, eventName) {
@@ -51,16 +52,18 @@ function fromEvent(target, eventName) {
 
 // #enddocregion fromevent
 
-// #docregion fromevent_use
+export function docRegionFromEvent(document) {
+  // #docregion fromevent_use
 
-const ESC_KEY = 27;
-const nameInput = document.getElementById('name') as HTMLInputElement;
+  const ESC_KEY = 27;
+  const nameInput = document.getElementById('name') as HTMLInputElement;
 
-const subscription = fromEvent(nameInput, 'keydown')
-  .subscribe((e: KeyboardEvent) => {
+  const subscription = fromEvent(nameInput, 'keydown').subscribe((e: KeyboardEvent) => {
     if (e.keyCode === ESC_KEY) {
       nameInput.value = '';
     }
   });
+  // #enddocregion fromevent_use
+  return subscription;
+}
 
-// #enddocregion fromevent_use

aio/content/examples/observables/src/geolocation.ts

@@ -1,5 +1,5 @@
+// TODO: Add unit tests for this file.
 import { Observable } from 'rxjs';
-
 // #docregion
 
 // Create an Observable that will start listening to geolocation updates

aio/content/examples/observables/src/multicasting.spec.ts

@@ -0,0 +1,48 @@
+import { docRegionDelaySequence, docRegionMulticastSequence } from './multicasting';
+
+describe('multicasting', () => {
+  let console;
+  beforeEach(() => {
+    jasmine.clock().install();
+    console = {log: jasmine.createSpy('log')};
+  });
+
+  afterEach(() => {
+    jasmine.clock().uninstall();
+  });
+
+  it('should create an observable and emit in sequence', () => {
+    docRegionDelaySequence(console);
+    jasmine.clock().tick(10000);
+    expect(console.log).toHaveBeenCalledTimes(12);
+    expect(console.log.calls.allArgs()).toEqual([
+      [1],
+      ['1st subscribe: 1'],
+      ['2nd subscribe: 1'],
+      [2],
+      ['1st subscribe: 2'],
+      ['2nd subscribe: 2'],
+      [3],
+      ['Finished sequence'],
+      ['1st subscribe: 3'],
+      ['1st sequence finished.'],
+      ['2nd subscribe: 3'],
+      ['2nd sequence finished.']
+    ]);
+  });
+
+  it('should create an observable and multicast the emissions', () => {
+    docRegionMulticastSequence(console);
+    jasmine.clock().tick(10000);
+    expect(console.log).toHaveBeenCalledTimes(7);
+    expect(console.log.calls.allArgs()).toEqual([
+      ['1st subscribe: 1'],
+      ['1st subscribe: 2'],
+      ['2nd subscribe: 2'],
+      ['1st subscribe: 3'],
+      ['2nd subscribe: 3'],
+      ['1st sequence finished.'],
+      ['2nd sequence finished.']
+    ]);
+  });
+});

aio/content/examples/observables/src/multicasting.ts

@@ -1,155 +1,160 @@
+// #docplaster
 
 import { Observable } from 'rxjs';
 
-// #docregion delay_sequence
+export function docRegionDelaySequence(console) {
+  // #docregion delay_sequence
+  function sequenceSubscriber(observer) {
+    const seq = [1, 2, 3];
+    let timeoutId;
 
-function sequenceSubscriber(observer) {
-  const seq = [1, 2, 3];
-  let timeoutId;
+    // Will run through an array of numbers, emitting one value
+    // per second until it gets to the end of the array.
+    function doInSequence(arr, idx) {
+      timeoutId = setTimeout(() => {
+        observer.next(arr[idx]);
+        if (idx === arr.length - 1) {
+          observer.complete();
+        } else {
+          doInSequence(arr, ++idx);
+        }
+      }, 1000);
+    }
 
-  // Will run through an array of numbers, emitting one value
+    doInSequence(seq, 0);
+
+    // Unsubscribe should clear the timeout to stop execution
+    return {
+      unsubscribe() {
+        clearTimeout(timeoutId);
+      }
+    };
+  }
+
+  // Create a new Observable that will deliver the above sequence
+  const sequence = new Observable(sequenceSubscriber);
+
+  sequence.subscribe({
+    next(num) { console.log(num); },
+    complete() { console.log('Finished sequence'); }
+  });
+
+  // Logs:
+  // (at 1 second): 1
+  // (at 2 seconds): 2
+  // (at 3 seconds): 3
+  // (at 3 seconds): Finished sequence
+
+  // #enddocregion delay_sequence
+
+  // #docregion subscribe_twice
+
+  // Subscribe starts the clock, and will emit after 1 second
+  sequence.subscribe({
+    next(num) { console.log('1st subscribe: ' + num); },
+    complete() { console.log('1st sequence finished.'); }
+  });
+
+  // After 1/2 second, subscribe again.
+  setTimeout(() => {
+    sequence.subscribe({
+      next(num) { console.log('2nd subscribe: ' + num); },
+      complete() { console.log('2nd sequence finished.'); }
+    });
+  }, 500);
+
+  // Logs:
+  // (at 1 second): 1st subscribe: 1
+  // (at 1.5 seconds): 2nd subscribe: 1
+  // (at 2 seconds): 1st subscribe: 2
+  // (at 2.5 seconds): 2nd subscribe: 2
+  // (at 3 seconds): 1st subscribe: 3
+  // (at 3 seconds): 1st sequence finished
+  // (at 3.5 seconds): 2nd subscribe: 3
+  // (at 3.5 seconds): 2nd sequence finished
+
+  // #enddocregion subscribe_twice
+}
+
+export function docRegionMulticastSequence(console) {
+  // #docregion multicast_sequence
+  function multicastSequenceSubscriber() {
+    const seq = [1, 2, 3];
+    // Keep track of each observer (one for every active subscription)
+    const observers = [];
+    // Still a single timeoutId because there will only ever be one
+    // set of values being generated, multicasted to each subscriber
+    let timeoutId;
+
+    // Return the subscriber function (runs when subscribe()
+    // function is invoked)
+    return observer => {
+      observers.push(observer);
+      // When this is the first subscription, start the sequence
+      if (observers.length === 1) {
+        timeoutId = doSequence({
+          next(val) {
+            // Iterate through observers and notify all subscriptions
+            observers.forEach(obs => obs.next(val));
+          },
+          complete() {
+            // Notify all complete callbacks
+            observers.slice(0).forEach(obs => obs.complete());
+          }
+        }, seq, 0);
+      }
+
+      return {
+        unsubscribe() {
+          // Remove from the observers array so it's no longer notified
+          observers.splice(observers.indexOf(observer), 1);
+          // If there's no more listeners, do cleanup
+          if (observers.length === 0) {
+            clearTimeout(timeoutId);
+          }
+        }
+      };
+    };
+  }
+
+  // Run through an array of numbers, emitting one value
   // per second until it gets to the end of the array.
-  function doInSequence(arr, idx) {
-    timeoutId = setTimeout(() => {
+  function doSequence(observer, arr, idx) {
+    return setTimeout(() => {
       observer.next(arr[idx]);
       if (idx === arr.length - 1) {
         observer.complete();
       } else {
-        doInSequence(arr, ++idx);
+        doSequence(observer, arr, ++idx);
       }
     }, 1000);
   }
 
-  doInSequence(seq, 0);
+  // Create a new Observable that will deliver the above sequence
+  const multicastSequence = new Observable(multicastSequenceSubscriber());
 
-  // Unsubscribe should clear the timeout to stop execution
-  return {unsubscribe() {
-    clearTimeout(timeoutId);
-  }};
-}
-
-// Create a new Observable that will deliver the above sequence
-const sequence = new Observable(sequenceSubscriber);
-
-sequence.subscribe({
-  next(num) { console.log(num); },
-  complete() { console.log('Finished sequence'); }
-});
-
-// Logs:
-// (at 1 second): 1
-// (at 2 seconds): 2
-// (at 3 seconds): 3
-// (at 3 seconds): Finished sequence
-
-// #enddocregion delay_sequence
-
-// #docregion subscribe_twice
-
-// Subscribe starts the clock, and will emit after 1 second
-sequence.subscribe({
-  next(num) { console.log('1st subscribe: ' + num); },
-  complete() { console.log('1st sequence finished.'); }
-});
-
-// After 1/2 second, subscribe again.
-setTimeout(() => {
-  sequence.subscribe({
-    next(num) { console.log('2nd subscribe: ' + num); },
-    complete() { console.log('2nd sequence finished.'); }
-  });
-}, 500);
-
-// Logs:
-// (at 1 second): 1st subscribe: 1
-// (at 1.5 seconds): 2nd subscribe: 1
-// (at 2 seconds): 1st subscribe: 2
-// (at 2.5 seconds): 2nd subscribe: 2
-// (at 3 seconds): 1st subscribe: 3
-// (at 3 seconds): 1st sequence finished
-// (at 3.5 seconds): 2nd subscribe: 3
-// (at 3.5 seconds): 2nd sequence finished
-
-// #enddocregion subscribe_twice
-
-// #docregion multicast_sequence
-
-function multicastSequenceSubscriber() {
-  const seq = [1, 2, 3];
-  // Keep track of each observer (one for every active subscription)
-  const observers = [];
-  // Still a single timeoutId because there will only ever be one
-  // set of values being generated, multicasted to each subscriber
-  let timeoutId;
-
-  // Return the subscriber function (runs when subscribe()
-  // function is invoked)
-  return (observer) => {
-    observers.push(observer);
-    // When this is the first subscription, start the sequence
-    if (observers.length === 1) {
-      timeoutId = doSequence({
-        next(val) {
-          // Iterate through observers and notify all subscriptions
-          observers.forEach(obs => obs.next(val));
-        },
-        complete() {
-          // Notify all complete callbacks
-          observers.slice(0).forEach(obs => obs.complete());
-        }
-      }, seq, 0);
-    }
-
-    return {
-      unsubscribe() {
-        // Remove from the observers array so it's no longer notified
-        observers.splice(observers.indexOf(observer), 1);
-        // If there's no more listeners, do cleanup
-        if (observers.length === 0) {
-          clearTimeout(timeoutId);
-        }
-      }
-    };
-  };
-}
-
-// Run through an array of numbers, emitting one value
-// per second until it gets to the end of the array.
-function doSequence(observer, arr, idx) {
-  return setTimeout(() => {
-    observer.next(arr[idx]);
-    if (idx === arr.length - 1) {
-      observer.complete();
-    } else {
-      doSequence(observer, arr, ++idx);
-    }
-  }, 1000);
-}
-
-// Create a new Observable that will deliver the above sequence
-const multicastSequence = new Observable(multicastSequenceSubscriber());
-
-// Subscribe starts the clock, and begins to emit after 1 second
-multicastSequence.subscribe({
-  next(num) { console.log('1st subscribe: ' + num); },
-  complete() { console.log('1st sequence finished.'); }
-});
-
-// After 1 1/2 seconds, subscribe again (should "miss" the first value).
-setTimeout(() => {
+  // Subscribe starts the clock, and begins to emit after 1 second
   multicastSequence.subscribe({
-    next(num) { console.log('2nd subscribe: ' + num); },
-    complete() { console.log('2nd sequence finished.'); }
+    next(num) { console.log('1st subscribe: ' + num); },
+    complete() { console.log('1st sequence finished.'); }
   });
-}, 1500);
 
-// Logs:
-// (at 1 second): 1st subscribe: 1
-// (at 2 seconds): 1st subscribe: 2
-// (at 2 seconds): 2nd subscribe: 2
-// (at 3 seconds): 1st subscribe: 3
-// (at 3 seconds): 1st sequence finished
-// (at 3 seconds): 2nd subscribe: 3
-// (at 3 seconds): 2nd sequence finished
+  // After 1 1/2 seconds, subscribe again (should "miss" the first value).
+  setTimeout(() => {
+    multicastSequence.subscribe({
+      next(num) { console.log('2nd subscribe: ' + num); },
+      complete() { console.log('2nd sequence finished.'); }
+    });
+  }, 1500);
 
-// #enddocregion multicast_sequence
+  // Logs:
+  // (at 1 second): 1st subscribe: 1
+  // (at 2 seconds): 1st subscribe: 2
+  // (at 2 seconds): 2nd subscribe: 2
+  // (at 3 seconds): 1st subscribe: 3
+  // (at 3 seconds): 1st sequence finished
+  // (at 3 seconds): 2nd subscribe: 3
+  // (at 3 seconds): 2nd sequence finished
+
+  // #enddocregion multicast_sequence
+}

aio/content/examples/observables/src/subscribing.spec.ts

@@ -0,0 +1,19 @@
+import { docRegionObserver } from './subscribing';
+
+describe('subscribing', () => {
+  it('should subscribe and emit', () => {
+    const console = {log: jasmine.createSpy('log')};
+    docRegionObserver(console);
+    expect(console.log).toHaveBeenCalledTimes(8);
+    expect(console.log.calls.allArgs()).toEqual([
+      ['Observer got a next value: 1'],
+      ['Observer got a next value: 2'],
+      ['Observer got a next value: 3'],
+      ['Observer got a complete notification'],
+      ['Observer got a next value: 1'],
+      ['Observer got a next value: 2'],
+      ['Observer got a next value: 3'],
+      ['Observer got a complete notification'],
+    ]);
+  });
+});

aio/content/examples/observables/src/subscribing.ts

@@ -1,32 +1,35 @@
+// #docplaster
+import { of } from 'rxjs';
 
-import { Observable, of } from 'rxjs';
+export function docRegionObserver(console) {
+  // #docregion observer
 
-// #docregion observer
+  // Create simple observable that emits three values
+  const myObservable = of(1, 2, 3);
 
-// Create simple observable that emits three values
-const myObservable = of(1, 2, 3);
+  // Create observer object
+  const myObserver = {
+    next: x => console.log('Observer got a next value: ' + x),
+    error: err => console.error('Observer got an error: ' + err),
+    complete: () => console.log('Observer got a complete notification'),
+  };
 
-// Create observer object
-const myObserver = {
-  next: x => console.log('Observer got a next value: ' + x),
-  error: err => console.error('Observer got an error: ' + err),
-  complete: () => console.log('Observer got a complete notification'),
-};
+  // Execute with the observer object
+  myObservable.subscribe(myObserver);
 
-// Execute with the observer object
-myObservable.subscribe(myObserver);
-// Logs:
-// Observer got a next value: 1
-// Observer got a next value: 2
-// Observer got a next value: 3
-// Observer got a complete notification
+  // Logs:
+  // Observer got a next value: 1
+  // Observer got a next value: 2
+  // Observer got a next value: 3
+  // Observer got a complete notification
 
-// #enddocregion observer
+  // #enddocregion observer
 
-// #docregion sub_fn
-myObservable.subscribe(
-  x => console.log('Observer got a next value: ' + x),
-  err => console.error('Observer got an error: ' + err),
-  () => console.log('Observer got a complete notification')
-);
-// #enddocregion sub_fn
+  // #docregion sub_fn
+  myObservable.subscribe(
+    x => console.log('Observer got a next value: ' + x),
+    err => console.error('Observer got an error: ' + err),
+    () => console.log('Observer got a complete notification')
+  );
+  // #enddocregion sub_fn
+}

aio/content/examples/practical-observable-usage/example-config.json

@@ -2,7 +2,11 @@
   "tests": [
     {
       "cmd": "yarn",
-      "args": [ "tsc", "--project", "./tsconfig.app.json" ]
+      "args": ["tsc", "--project", "tsconfig.spec.json", "--module", "commonjs"]
+    },
+    {
+      "cmd": "yarn",
+      "args": ["jasmine", "out-tsc/**/*.spec.js"]
     }
   ]
 }

aio/content/examples/practical-observable-usage/src/backoff.spec.ts

@@ -0,0 +1,70 @@
+import { interval } from 'rxjs';
+import { tap } from 'rxjs/operators';
+import { backoff } from './backoff';
+
+describe('backoff()', () => {
+  beforeEach(() => jasmine.clock().install());
+  afterEach(() => jasmine.clock().uninstall());
+
+  it('should retry in case of error', () => {
+    const mockConsole = {log: jasmine.createSpy('log')};
+    const source = interval(10).pipe(
+      tap(i => {
+        if (i > 0) {
+          throw new Error('Test error');
+        }
+      }),
+      backoff(3, 100),
+    );
+    source.subscribe({
+      next: v => mockConsole.log(`Emitted: ${v}`),
+      error: e => mockConsole.log(`Errored: ${e.message || e}`),
+      complete: () => mockConsole.log('Completed'),
+    });
+
+    // Initial try:
+    // Errors on second emission and schedules retrying (with delay).
+    jasmine.clock().tick(10);
+    expect(mockConsole.log.calls.allArgs()).toEqual([['Emitted: 0']]);
+
+    jasmine.clock().tick(10);
+    expect(mockConsole.log.calls.allArgs()).toEqual([['Emitted: 0']]);
+    mockConsole.log.calls.reset();
+
+    // First re-attempt after 100ms:
+    // Errors again on second emission and schedules retrying (with larger delay).
+    jasmine.clock().tick(100);
+    expect(mockConsole.log).not.toHaveBeenCalled();
+
+    jasmine.clock().tick(10);
+    expect(mockConsole.log.calls.allArgs()).toEqual([['Emitted: 0']]);
+
+    jasmine.clock().tick(10);
+    expect(mockConsole.log.calls.allArgs()).toEqual([['Emitted: 0']]);
+    mockConsole.log.calls.reset();
+
+    // Second re-attempt after 400ms:
+    // Errors again on second emission and schedules retrying (with even larger delay).
+    jasmine.clock().tick(400);
+    expect(mockConsole.log).not.toHaveBeenCalled();
+
+    jasmine.clock().tick(10);
+    expect(mockConsole.log.calls.allArgs()).toEqual([['Emitted: 0']]);
+
+    jasmine.clock().tick(10);
+    expect(mockConsole.log.calls.allArgs()).toEqual([['Emitted: 0']]);
+    mockConsole.log.calls.reset();
+
+    // Third re-attempt after 900ms:
+    // Errors again on second emission and gives up (no retrying).
+    jasmine.clock().tick(900);
+    expect(mockConsole.log).not.toHaveBeenCalled();
+
+    jasmine.clock().tick(10);
+    expect(mockConsole.log.calls.allArgs()).toEqual([['Emitted: 0']]);
+    mockConsole.log.calls.reset();
+
+    jasmine.clock().tick(10);
+    expect(mockConsole.log.calls.allArgs()).toEqual([['Errored: Test error']]);
+  });
+});

aio/content/examples/practical-observable-usage/src/backoff.ts

@@ -1,23 +1,32 @@
-
-import { pipe, range, timer, zip } from 'rxjs';
+// #docplaster
+// #docregion
+import { of, pipe, range, throwError, timer, zip } from 'rxjs';
 import { ajax } from 'rxjs/ajax';
-import { retryWhen, map, mergeMap } from 'rxjs/operators';
+import { map, mergeMap, retryWhen } from 'rxjs/operators';
 
-function backoff(maxTries, ms) {
- return pipe(
-   retryWhen(attempts => zip(range(1, maxTries), attempts)
-     .pipe(
-       map(([i]) => i * i),
-       mergeMap(i =>  timer(i * ms))
-     )
-   )
- );
+export function backoff(maxTries, delay) {
+  return pipe(
+    retryWhen(attempts =>
+      zip(range(1, maxTries + 1), attempts).pipe(
+        mergeMap(([i, err]) => (i > maxTries) ? throwError(err) : of(i)),
+        map(i => i * i),
+        mergeMap(v => timer(v * delay)),
+      ),
+    ),
+  );
 }
 
+// #enddocregion
+/*
+  This function declaration is necessary to ensure that it does not get called
+  when running the unit tests. It will not get rendered into the docs.
+  The indentation needs to start in the leftmost level position as well because of how
+  the docplaster combines the different regions together.
+*/
+function docRegionAjaxCall() {
+// #docregion
 ajax('/api/endpoint')
   .pipe(backoff(3, 250))
-  .subscribe(data => handleData(data));
-
-function handleData(data) {
-  // ...
+  .subscribe(function handleData(data) { /* ... */ });
+// #enddocregion
 }

aio/content/examples/practical-observable-usage/src/typeahead.spec.ts

@@ -0,0 +1,72 @@
+import { of } from 'rxjs';
+import { docRegionTypeahead } from './typeahead';
+
+describe('typeahead', () => {
+  let document;
+  let ajax;
+  let triggertInputChange;
+
+  beforeEach(() => {
+    jasmine.clock().install();
+    const input = {
+      addEventListener: jasmine
+        .createSpy('addEvent')
+        .and.callFake((eventName: string, cb: (e) => void) => {
+          if (eventName === 'input') {
+            triggertInputChange = cb;
+          }
+        }),
+      removeEventListener: jasmine.createSpy('removeEvent'),
+    };
+
+    document = { getElementById: (id: string) => input };
+    ajax = jasmine.createSpy('ajax').and.callFake((url: string) => of('foo bar'));
+  });
+
+  afterEach(() => {
+    jasmine.clock().uninstall();
+  });
+
+  it('should make an ajax call to the corrent endpoint', () => {
+    docRegionTypeahead(document, ajax);
+    triggertInputChange({ target: { value: 'foo' } });
+    jasmine.clock().tick(11);
+    expect(ajax).toHaveBeenCalledWith('/api/endpoint?search=foo');
+  });
+
+  it('should not make an ajax call, when the input length < 3', () => {
+    docRegionTypeahead(document, ajax);
+    triggertInputChange({ target: { value: '' } });
+    jasmine.clock().tick(11);
+    expect(ajax).not.toHaveBeenCalled();
+    triggertInputChange({ target: { value: 'fo' } });
+    jasmine.clock().tick(11);
+    expect(ajax).not.toHaveBeenCalled();
+  });
+
+  it('should not make an ajax call for intermediate values when debouncing', () => {
+    docRegionTypeahead(document, ajax);
+    triggertInputChange({ target: { value: 'foo' } });
+    jasmine.clock().tick(9);
+    triggertInputChange({ target: { value: 'bar' } });
+    jasmine.clock().tick(9);
+    triggertInputChange({ target: { value: 'baz' } });
+    jasmine.clock().tick(9);
+    triggertInputChange({ target: { value: 'qux' } });
+    expect(ajax).not.toHaveBeenCalled();
+    jasmine.clock().tick(10);
+    expect(ajax).toHaveBeenCalledTimes(1);
+    expect(ajax).toHaveBeenCalledWith('/api/endpoint?search=qux');
+  });
+
+  it('should not make an ajax call, when the input value has not changed', () => {
+    docRegionTypeahead(document, ajax);
+    triggertInputChange({ target: { value: 'foo' } });
+    jasmine.clock().tick(11);
+    expect(ajax).toHaveBeenCalled();
+    ajax.calls.reset();
+    triggertInputChange({ target: { value: 'foo' } });
+    jasmine.clock().tick(11);
+    expect(ajax).not.toHaveBeenCalled();
+  });
+});

aio/content/examples/practical-observable-usage/src/typeahead.ts

@@ -1,18 +1,32 @@
-import { fromEvent } from 'rxjs';
-import { ajax } from 'rxjs/ajax';
-import { debounceTime, distinctUntilChanged, filter, map, switchMap } from 'rxjs/operators';
+/*
+  Because of how the code is merged together using the doc regions,
+  we need to indent the imports with the function below.
+*/
+// #docplaster
+// #docregion
+  import { fromEvent } from 'rxjs';
+  import { ajax } from 'rxjs/ajax';
+  import { debounceTime, distinctUntilChanged, filter, map, switchMap } from 'rxjs/operators';
 
+// #enddocregion
+/* tslint:disable:no-shadowed-variable */
+/* tslint:disable:align */
+export function docRegionTypeahead(document, ajax) {
+  // #docregion
+  const searchBox = document.getElementById('search-box');
 
-const searchBox = document.getElementById('search-box');
+  const typeahead = fromEvent(searchBox, 'input').pipe(
+    map((e: KeyboardEvent) => (e.target as HTMLInputElement).value),
+    filter(text => text.length > 2),
+    debounceTime(10),
+    distinctUntilChanged(),
+    switchMap(searchTerm => ajax(`/api/endpoint?search=${searchTerm}`))
+  );
 
-const typeahead = fromEvent(searchBox, 'input').pipe(
-  map((e: KeyboardEvent) => (e.target as HTMLInputElement).value),
-  filter(text => text.length > 2),
-  debounceTime(10),
-  distinctUntilChanged(),
-  switchMap(() => ajax('/api/endpoint'))
-);
+  typeahead.subscribe(data => {
+    // Handle the data from the API
+  });
 
-typeahead.subscribe(data => {
- // Handle the data from the API
-});
+  // #enddocregion
+  return typeahead;
+}

aio/content/examples/rx-library/example-config.json

@@ -2,7 +2,11 @@
   "tests": [
     {
       "cmd": "yarn",
-      "args": [ "tsc", "--project", "./tsconfig.app.json" ]
+      "args": ["tsc", "--project", "tsconfig.spec.json", "--module", "commonjs"]
+    },
+    {
+      "cmd": "yarn",
+      "args": ["jasmine", "out-tsc/**/*.spec.js"]
     }
   ]
 }

aio/content/examples/rx-library/src/error-handling.spec.ts

@@ -0,0 +1,46 @@
+import { Subject, throwError } from 'rxjs';
+import { docRegionDefault } from './error-handling';
+
+describe('error-handling', () => {
+  let mockConsole;
+  let ajaxSubject;
+  let ajax;
+
+  beforeEach(() => {
+    mockConsole = {log: jasmine.createSpy('log')};
+    ajaxSubject = new Subject();
+    ajax = jasmine
+      .createSpy('ajax')
+      .and.callFake((url: string) => ajaxSubject);
+  });
+
+  afterEach(() => ajaxSubject.unsubscribe());
+
+  it('should return the response object', () => {
+    docRegionDefault(mockConsole, ajax);
+
+    ajaxSubject.next({response: {foo: 'bar'}});
+    expect(mockConsole.log.calls.allArgs()).toEqual([
+      ['data: ', {foo: 'bar'}]
+    ]);
+  });
+
+  it('should return an empty array when using an object without a `response` property', () => {
+    docRegionDefault(mockConsole, ajax);
+
+    ajaxSubject.next({foo: 'bar'});
+    expect(mockConsole.log.calls.allArgs()).toEqual([
+      ['data: ', []]
+    ]);
+  });
+
+  it('should return an empty array when the ajax observable errors', () => {
+    ajax.and.returnValue(throwError('Test Error'));
+
+    docRegionDefault(mockConsole, ajax);
+
+    expect(mockConsole.log.calls.allArgs()).toEqual([
+      ['data: ', []]
+    ]);
+  });
+});

aio/content/examples/rx-library/src/error-handling.ts

@@ -1,25 +1,36 @@
-
-import { of } from 'rxjs';
-
+// #docplaster
+/*
+  Because of how the code is merged together using the doc regions,
+  we need to indent the imports with the function below.
+*/
+/* tslint:disable:no-shadowed-variable */
+/* tslint:disable:align */
 // #docregion
-
-import { ajax } from 'rxjs/ajax';
-import { map, catchError } from 'rxjs/operators';
-// Return "response" from the API. If an error happens,
-// return an empty array.
-const apiData = ajax('/api/data').pipe(
-  map(res => {
-    if (!res.response) {
-      throw new Error('Value expected!');
-    }
-    return res.response;
-  }),
-  catchError(err => of([]))
-);
-
-apiData.subscribe({
-  next(x) { console.log('data: ', x); },
-  error(err) { console.log('errors already caught... will not run'); }
-});
+  import { of } from 'rxjs';
+  import { ajax } from 'rxjs/ajax';
+  import { map, catchError } from 'rxjs/operators';
 
 // #enddocregion
+
+export function docRegionDefault(console, ajax) {
+  // #docregion
+  // Return "response" from the API. If an error happens,
+  // return an empty array.
+  const apiData = ajax('/api/data').pipe(
+    map((res: any) => {
+      if (!res.response) {
+        throw new Error('Value expected!');
+      }
+      return res.response;
+    }),
+    catchError(err => of([]))
+  );
+
+  apiData.subscribe({
+    next(x) { console.log('data: ', x); },
+    error(err) { console.log('errors already caught... will not run'); }
+  });
+
+  // #enddocregion
+  return apiData;
+}

aio/content/examples/rx-library/src/operators.1.spec.ts

@@ -0,0 +1,14 @@
+import { docRegionDefault } from './operators.1';
+
+describe('squareOdd - operators.1.ts', () => {
+  it('should return square odds', () => {
+    const console = {log: jasmine.createSpy('log')};
+    docRegionDefault(console);
+    expect(console.log).toHaveBeenCalledTimes(3);
+    expect(console.log.calls.allArgs()).toEqual([
+      [1],
+      [9],
+      [25],
+    ]);
+  });
+});

aio/content/examples/rx-library/src/operators.1.ts

@@ -1,23 +1,30 @@
-import { of, pipe } from 'rxjs';
-
+// #docplaster
+/*
+  Because of how the code is merged together using the doc regions,
+  we need to indent the imports with the function below.
+*/
+/* tslint:disable:align */
 // #docregion
-
-import { filter, map } from 'rxjs/operators';
-
-const nums = of(1, 2, 3, 4, 5);
-
-// Create a function that accepts an Observable.
-const squareOddVals = pipe(
-  filter((n: number) => n % 2 !== 0),
-  map(n => n * n)
-);
-
-// Create an Observable that will run the filter and map functions
-const squareOdd = squareOddVals(nums);
-
-// Subscribe to run the combined functions
-squareOdd.subscribe(x => console.log(x));
+  import { of, pipe } from 'rxjs';
+  import { filter, map } from 'rxjs/operators';
 
 // #enddocregion
 
+export function docRegionDefault(console) {
+  // #docregion
+  const nums = of(1, 2, 3, 4, 5);
 
+  // Create a function that accepts an Observable.
+  const squareOddVals = pipe(
+    filter((n: number) => n % 2 !== 0),
+    map(n => n * n)
+  );
+
+  // Create an Observable that will run the filter and map functions
+  const squareOdd = squareOddVals(nums);
+
+  // Subscribe to run the combined functions
+  squareOdd.subscribe(x => console.log(x));
+
+  // #enddocregion
+}

aio/content/examples/rx-library/src/operators.2.spec.ts

@@ -0,0 +1,14 @@
+import { docRegionDefault } from './operators.2';
+
+describe('squareOdd - operators.2.ts', () => {
+  it('should return square odds', () => {
+    const console = {log: jasmine.createSpy('log')};
+    docRegionDefault(console);
+    expect(console.log).toHaveBeenCalledTimes(3);
+    expect(console.log.calls.allArgs()).toEqual([
+      [1],
+      [9],
+      [25],
+    ]);
+  });
+});

aio/content/examples/rx-library/src/operators.2.ts

@@ -1,16 +1,25 @@
-import { Observable, of } from 'rxjs';
-
+// #docplaster
+/*
+  Because of how the code is merged together using the doc regions,
+  we need to indent the imports with the function below.
+*/
+/* tslint:disable:align */
 // #docregion
-
-import { filter, map } from 'rxjs/operators';
-
-const squareOdd = of(1, 2, 3, 4, 5)
-  .pipe(
-    filter(n => n % 2 !== 0),
-    map(n => n * n)
-  );
-
-// Subscribe to get values
-squareOdd.subscribe(x => console.log(x));
+  import { of } from 'rxjs';
+  import { filter, map } from 'rxjs/operators';
 
 // #enddocregion
+
+export function docRegionDefault(console) {
+  // #docregion
+  const squareOdd = of(1, 2, 3, 4, 5)
+    .pipe(
+      filter(n => n % 2 !== 0),
+      map(n => n * n)
+    );
+
+  // Subscribe to get values
+  squareOdd.subscribe(x => console.log(x));
+
+  // #enddocregion
+}

aio/content/examples/rx-library/src/operators.spec.ts

@@ -0,0 +1,14 @@
+import { docRegionDefault } from './operators';
+
+describe('squaredNums - operators.ts', () => {
+  it('should return square odds', () => {
+    const console = {log: jasmine.createSpy('log')};
+    docRegionDefault(console);
+    expect(console.log).toHaveBeenCalledTimes(3);
+    expect(console.log.calls.allArgs()).toEqual([
+      [1],
+      [4],
+      [9],
+    ]);
+  });
+});

aio/content/examples/rx-library/src/operators.ts

@@ -1,20 +1,28 @@
-
-import { Observable, of } from 'rxjs';
-
+// #docplaster
+/*
+  Because of how the code is merged together using the doc regions,
+  we need to indent the imports with the function below.
+*/
+/* tslint:disable:align */
 // #docregion
-
-import { map } from 'rxjs/operators';
-
-const nums = of(1, 2, 3);
-
-const squareValues = map((val: number) => val * val);
-const squaredNums = squareValues(nums);
-
-squaredNums.subscribe(x => console.log(x));
-
-// Logs
-// 1
-// 4
-// 9
+  import { of } from 'rxjs';
+  import { map } from 'rxjs/operators';
 
 // #enddocregion
+
+export function docRegionDefault(console) {
+  // #docregion
+  const nums = of(1, 2, 3);
+
+  const squareValues = map((val: number) => val * val);
+  const squaredNums = squareValues(nums);
+
+  squaredNums.subscribe(x => console.log(x));
+
+  // Logs
+  // 1
+  // 4
+  // 9
+
+  // #enddocregion
+}

aio/content/examples/rx-library/src/retry-on-error.spec.ts

@@ -0,0 +1,69 @@
+import { of, throwError } from 'rxjs';
+import { mergeMap, tap } from 'rxjs/operators';
+import { docRegionDefault } from './retry-on-error';
+
+describe('retry-on-error', () => {
+  let mockConsole;
+  beforeEach(() => mockConsole = { log: jasmine.createSpy('log') });
+
+  it('should return the response object', () => {
+    const ajax = () => of({ response: { foo: 'bar' } });
+
+    docRegionDefault(mockConsole, ajax);
+    expect(mockConsole.log.calls.allArgs()).toEqual([
+      ['data: ', { foo: 'bar' }],
+    ]);
+  });
+
+  it('should return an empty array after 3 retries + 1 initial request', () => {
+    const ajax = () => {
+      return of({ noresponse: true }).pipe(tap(() => mockConsole.log('Subscribed to AJAX')));
+    };
+
+    docRegionDefault(mockConsole, ajax);
+    expect(mockConsole.log.calls.allArgs()).toEqual([
+      ['Subscribed to AJAX'],
+      ['Error occured.'],
+      ['Subscribed to AJAX'],
+      ['Error occured.'],
+      ['Subscribed to AJAX'],
+      ['Error occured.'],
+      ['Subscribed to AJAX'],
+      ['Error occured.'],
+      ['data: ', []],
+    ]);
+  });
+
+  it('should return the response if the request succeeds upon retrying', () => {
+    // Fail on the first two requests, but succeed from the 3rd onwards.
+    let failCount = 2;
+    const ajax = () => of(null).pipe(
+      tap(() => mockConsole.log('Subscribed to AJAX')),
+      // Fail on the first 2 requests, but succeed from the 3rd onwards.
+      mergeMap(() => {
+        if (failCount > 0) {
+          failCount--;
+          return throwError('Test error');
+        }
+        return of({ response: { foo: 'bar' } });
+      }),
+    );
+
+    docRegionDefault(mockConsole, ajax);
+    expect(mockConsole.log.calls.allArgs()).toEqual([
+      ['Subscribed to AJAX'],  // Initial request   | 1st attempt overall
+      ['Subscribed to AJAX'],  // 1st retry attempt | 2nd attempt overall
+      ['Subscribed to AJAX'],  // 2nd retry attempt | 3rd attempt overall
+      ['data: ', { foo: 'bar' }],
+    ]);
+  });
+
+  it('should return an empty array when the ajax observable throws an error', () => {
+    const ajax = () => throwError('Test Error');
+
+    docRegionDefault(mockConsole, ajax);
+    expect(mockConsole.log.calls.allArgs()).toEqual([
+      ['data: ', []],
+    ]);
+  });
+});

aio/content/examples/rx-library/src/retry-on-error.ts

@@ -1,26 +1,35 @@
-
-import { Observable, of } from 'rxjs';
-
-
+// #docplaster
+/*
+  Because of how the code is merged together using the doc regions,
+  we need to indent the imports with the function below.
+*/
+/* tslint:disable:no-shadowed-variable */
+/* tslint:disable:align */
 // #docregion
-
-import { ajax } from 'rxjs/ajax';
-import { map, retry, catchError } from 'rxjs/operators';
-
-const apiData = ajax('/api/data').pipe(
-  retry(3), // Retry up to 3 times before failing
-  map(res => {
-    if (!res.response) {
-      throw new Error('Value expected!');
-    }
-    return res.response;
-  }),
-  catchError(err => of([]))
-);
-
-apiData.subscribe({
-  next(x) { console.log('data: ', x); },
-  error(err) { console.log('errors already caught... will not run'); }
-});
+  import { of } from 'rxjs';
+  import { ajax } from 'rxjs/ajax';
+  import { map, retry, catchError } from 'rxjs/operators';
 
 // #enddocregion
+
+export function docRegionDefault(console, ajax) {
+  // #docregion
+  const apiData = ajax('/api/data').pipe(
+    map((res: any) => {
+      if (!res.response) {
+        console.log('Error occured.');
+        throw new Error('Value expected!');
+      }
+      return res.response;
+    }),
+    retry(3), // Retry up to 3 times before failing
+    catchError(err => of([]))
+  );
+
+  apiData.subscribe({
+    next(x) { console.log('data: ', x); },
+    error(err) { console.log('errors already caught... will not run'); }
+  });
+
+  // #enddocregion
+}

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

@@ -0,0 +1,14 @@
+import { of } from 'rxjs';
+import { docRegionPromise } from './simple-creation.1';
+
+describe('simple-creation.1', () => {
+  it('should create a promise from an observable and return an empty object', () => {
+    const console = {log: jasmine.createSpy('log')};
+    const fetch = () => of({foo: 42});
+    docRegionPromise(console, fetch);
+    expect(console.log.calls.allArgs()).toEqual([
+      [{foo: 42}],
+      ['Completed'],
+    ]);
+  });
+});

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

@@ -0,0 +1,24 @@
+// #docplaster
+/*
+  Because of how the code is merged together using the doc regions,
+  we need to indent the imports with the function below.
+*/
+/* tslint:disable:align */
+// #docregion promise
+  import { from } from 'rxjs';
+
+// #enddocregion promise
+
+export function docRegionPromise(console, fetch) {
+  // #docregion promise
+  // Create an Observable out of a promise
+  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'); }
+  });
+
+  // #enddocregion promise
+}

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

@@ -0,0 +1,21 @@
+import { docRegionInterval } from './simple-creation.2';
+
+describe('simple-creation.2', () => {
+  beforeEach(() => jasmine.clock().install());
+  afterEach(() => jasmine.clock().uninstall());
+
+  it('should create an Observable that will publish a value on an interval', () => {
+    const console = {log: jasmine.createSpy('log')};
+    const subscription = docRegionInterval(console);
+    jasmine.clock().tick(1000);
+    expect(console.log).toHaveBeenCalledWith('It\'s been 1 seconds since subscribing!');
+    console.log.calls.reset();
+
+    jasmine.clock().tick(999);
+    expect(console.log).not.toHaveBeenCalled();
+
+    jasmine.clock().tick(1);
+    expect(console.log).toHaveBeenCalledWith('It\'s been 2 seconds since subscribing!');
+    subscription.unsubscribe();
+  });
+});

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

@@ -0,0 +1,22 @@
+// #docplaster
+/*
+  Because of how the code is merged together using the doc regions,
+  we need to indent the imports with the function below.
+*/
+/* tslint:disable:align */
+// #docregion interval
+  import { interval } from 'rxjs';
+
+// #enddocregion interval
+
+export function docRegionInterval(console) {
+  // #docregion interval
+  // Create an Observable that will publish a value on an interval
+  const secondsCounter = interval(1000);
+  // Subscribe to begin publishing values
+  const subscription = secondsCounter.subscribe(n =>
+    console.log(`It's been ${n + 1} seconds since subscribing!`));
+
+  // #enddocregion interval
+  return subscription;
+}

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

@@ -0,0 +1,53 @@
+import { docRegionEvent } from './simple-creation.3';
+
+describe('simple-creation.3', () => {
+  let triggerMousemove;
+  let mockConsole;
+  let input;
+  let mockDocument;
+
+  beforeEach(() => {
+    mockConsole = {log: jasmine.createSpy('log')};
+    input = {
+      addEventListener: jasmine
+        .createSpy('addEventListener')
+        .and.callFake((eventName, cb) => {
+          if (eventName === 'mousemove') {
+            triggerMousemove = cb;
+          }
+        }),
+      removeEventListener: jasmine.createSpy('removeEventListener'),
+    };
+    mockDocument = { getElementById: () => input };
+  });
+
+  it('should log coords when subscribing', () => {
+    docRegionEvent(mockConsole, mockDocument);
+
+    expect(mockConsole.log).not.toHaveBeenCalled();
+
+    triggerMousemove({ clientX: 50, clientY: 50 });
+    triggerMousemove({ clientX: 30, clientY: 50 });
+    triggerMousemove({ clientX: 50, clientY: 30 });
+    expect(mockConsole.log).toHaveBeenCalledTimes(3);
+    expect(mockConsole.log.calls.allArgs()).toEqual([
+      ['Coords: 50 X 50'],
+      ['Coords: 30 X 50'],
+      ['Coords: 50 X 30']
+    ]);
+  });
+
+  it('should call unsubscribe when clientX and clientY are below < 40 ', () => {
+    docRegionEvent(mockConsole, mockDocument);
+
+    expect(mockConsole.log).not.toHaveBeenCalled();
+
+    // Ensure that we have unsubscribed.
+    triggerMousemove({ clientX: 30, clientY: 30 });
+    expect(input.removeEventListener).toHaveBeenCalledWith('mousemove', triggerMousemove, undefined);
+    mockConsole.log.calls.reset();
+
+    triggerMousemove({ clientX: 50, clientY: 50 });
+    expect(mockConsole.log).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,32 @@
+// #docplaster
+/*
+  Because of how the code is merged together using the doc regions,
+  we need to indent the imports with the function below.
+*/
+/* tslint:disable:align */
+// #docregion event
+  import { fromEvent } from 'rxjs';
+
+// #enddocregion event
+
+export function docRegionEvent(console, document) {
+  // #docregion event
+  const el = document.getElementById('my-element');
+
+  // Create an Observable that will publish mouse movements
+  const mouseMoves = fromEvent(el, 'mousemove');
+
+  // Subscribe to start listening for mouse-move events
+  const subscription = mouseMoves.subscribe((evt: MouseEvent) => {
+    // Log coords of mouse movements
+    console.log(`Coords: ${evt.clientX} X ${evt.clientY}`);
+
+    // When the mouse is over the upper-left of the screen,
+    // unsubscribe to stop listening for mouse movements
+    if (evt.clientX < 40 && evt.clientY < 40) {
+      subscription.unsubscribe();
+    }
+  });
+
+  // #enddocregion event
+}

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

@@ -0,0 +1,14 @@
+import { of } from 'rxjs';
+import { docRegionAjax } from './simple-creation';
+
+describe('ajax', () => {
+  it('should make a request and console log the status and response', () => {
+    const console = {log: jasmine.createSpy('log')};
+    const ajax = jasmine.createSpy('ajax').and.callFake((url: string) => {
+      return of({status: 200, response: 'foo bar'});
+    });
+
+    docRegionAjax(console, ajax);
+    expect(console.log).toHaveBeenCalledWith(200, 'foo bar');
+  });
+});

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

@@ -1,65 +1,19 @@
-
-// #docregion promise
-
-import { from } from 'rxjs';
-
-// Create an Observable out of a promise
-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'); }
-});
-
-// #enddocregion promise
-
-// #docregion interval
-
-import { interval } from 'rxjs';
-
-// Create an Observable that will publish a value on an interval
-const secondsCounter = interval(1000);
-// Subscribe to begin publishing values
-secondsCounter.subscribe(n =>
-  console.log(`It's been ${n} seconds since subscribing!`));
-
-// #enddocregion interval
-
-
-// #docregion event
-
-import { fromEvent } from 'rxjs';
-
-const el = document.getElementById('my-element');
-
-// Create an Observable that will publish mouse movements
-const mouseMoves = fromEvent(el, 'mousemove');
-
-// Subscribe to start listening for mouse-move events
-const subscription = mouseMoves.subscribe((evt: MouseEvent) => {
-  // Log coords of mouse movements
-  console.log(`Coords: ${evt.clientX} X ${evt.clientY}`);
-
-  // When the mouse is over the upper-left of the screen,
-  // unsubscribe to stop listening for mouse movements
-  if (evt.clientX < 40 && evt.clientY < 40) {
-    subscription.unsubscribe();
-  }
-});
-
-// #enddocregion event
-
-
+// #docplaster
+/*
+  Because of how the code is merged together using the doc regions,
+  we need to indent the imports with the function below.
+*/
+/* tslint:disable:no-shadowed-variable */
+/* tslint:disable:align */
 // #docregion ajax
-
-import { ajax } from 'rxjs/ajax';
+  import { ajax } from 'rxjs/ajax';
 
 // Create an Observable that will create an AJAX request
-const apiData = ajax('/api/data');
-// Subscribe to create the request
-apiData.subscribe(res => console.log(res.status, res.response));
-
 // #enddocregion ajax
-
-
+export function docRegionAjax(console, ajax) {
+  // #docregion ajax
+  const apiData = ajax('/api/data');
+  // Subscribe to create the request
+  apiData.subscribe(res => console.log(res.status, res.response));
+  // #enddocregion ajax
+}

aio/content/examples/testing/src/app/demo/demo.testbed.spec.ts

@@ -28,7 +28,7 @@ import {
   ComponentFixture, fakeAsync, inject, TestBed, tick, waitForAsync
 } from '@angular/core/testing';
 
-import { addMatchers, newEvent, click } from '../../testing';
+import { addMatchers, click } from '../../testing';
 
 export class NotProvided extends ValueService { /* example below */ }
 beforeEach(addMatchers);
@@ -274,9 +274,11 @@ describe('demo (with TestBed):', () => {
         expect(comp.name).toBe(expectedOrigName,
           `comp.name should still be ${expectedOrigName} after value change, before binding happens`);
 
-        // dispatch a DOM event so that Angular learns of input value change.
+        // Dispatch a DOM event so that Angular learns of input value change.
         // then wait while ngModel pushes input.box value to comp.name
-        input.dispatchEvent(newEvent('input'));
+        // In older browsers, such as IE, you might need a CustomEvent instead. See
+        // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+        input.dispatchEvent(new Event('input'));
         return fixture.whenStable();
       })
         .then(() => {
@@ -312,9 +314,11 @@ describe('demo (with TestBed):', () => {
       expect(comp.name).toBe(expectedOrigName,
         `comp.name should still be ${expectedOrigName} after value change, before binding happens`);
 
-      // dispatch a DOM event so that Angular learns of input value change.
+      // Dispatch a DOM event so that Angular learns of input value change.
       // then wait a tick while ngModel pushes input.box value to comp.name
-      input.dispatchEvent(newEvent('input'));
+      // In older browsers, such as IE, you might need a CustomEvent instead. See
+      // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+      input.dispatchEvent(new Event('input'));
       tick();
       expect(comp.name).toBe(expectedNewName,
         `After ngModel updates the model, comp.name should be ${expectedNewName} `);
@@ -335,10 +339,12 @@ describe('demo (with TestBed):', () => {
       // simulate user entering new name in input
       input.value = inputText;
 
-      // dispatch a DOM event so that Angular learns of input value change.
+      // Dispatch a DOM event so that Angular learns of input value change.
       // then wait a tick while ngModel pushes input.box value to comp.text
       // and Angular updates the output span
-      input.dispatchEvent(newEvent('input'));
+      // In older browsers, such as IE, you might need a CustomEvent instead. See
+      // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+      input.dispatchEvent(new Event('input'));
       tick();
       fixture.detectChanges();
       expect(span.textContent).toBe(expectedText, 'output span');

aio/content/examples/testing/src/app/hero/hero-detail.component.spec.ts

@@ -3,7 +3,7 @@ import { ComponentFixture, fakeAsync, inject, TestBed, tick, waitForAsync } from
 import { Router } from '@angular/router';
 
 import {
-  ActivatedRoute, ActivatedRouteStub, asyncData, click, newEvent
+  ActivatedRoute, ActivatedRouteStub, asyncData, click
 } from '../../testing';
 
 import { Hero } from '../model/hero';
@@ -99,7 +99,10 @@ function overrideSetup() {
        const newName = 'New Name';
 
        page.nameInput.value = newName;
-       page.nameInput.dispatchEvent(newEvent('input'));  // tell Angular
+
+       // In older browsers, such as IE, you might need a CustomEvent instead. See
+       // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+       page.nameInput.dispatchEvent(new Event('input')); // tell Angular
 
        expect(component.hero.name).toBe(newName, 'component hero has new name');
        expect(hdsSpy.testHero.name).toBe(origName, 'service hero unchanged before save');
@@ -197,9 +200,10 @@ function heroModuleSetup() {
       // simulate user entering a new name into the input box
       nameInput.value = 'quick BROWN  fOx';
 
-      // dispatch a DOM event so that Angular learns of input value change.
-      // use newEvent utility function (not provided by Angular) for better browser compatibility
-      nameInput.dispatchEvent(newEvent('input'));
+      // Dispatch a DOM event so that Angular learns of input value change.
+      // In older browsers, such as IE, you might need a CustomEvent instead. See
+      // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+      nameInput.dispatchEvent(new Event('input'));
 
       // Tell Angular to update the display binding through the title pipe
       fixture.detectChanges();

aio/content/examples/testing/src/app/hero/hero-list.component.spec.ts

@@ -6,7 +6,7 @@ import { DebugElement } from '@angular/core';
 
 import { Router } from '@angular/router';
 
-import { addMatchers, newEvent } from '../../testing';
+import { addMatchers } from '../../testing';
 import { HeroService } from '../model/hero.service';
 import { getTestHeroes, TestHeroService } from '../model/testing/test-hero.service';
 
@@ -53,7 +53,10 @@ describe('HeroListComponent', () => {
   it('should select hero on click', fakeAsync(() => {
        const expectedHero = HEROES[1];
        const li = page.heroRows[1];
-       li.dispatchEvent(newEvent('click'));
+
+       // In older browsers, such as IE, you might need a CustomEvent instead. See
+       // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+       li.dispatchEvent(new Event('click'));
        tick();
        // `.toEqual` because selectedHero is clone of expectedHero; see FakeHeroService
        expect(comp.selectedHero).toEqual(expectedHero);
@@ -62,7 +65,10 @@ describe('HeroListComponent', () => {
   it('should navigate to selected hero detail on click', fakeAsync(() => {
        const expectedHero = HEROES[1];
        const li = page.heroRows[1];
-       li.dispatchEvent(newEvent('click'));
+
+       // In older browsers, such as IE, you might need a CustomEvent instead. See
+       // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+       li.dispatchEvent(new Event('click'));
        tick();
 
        // should have navigated

aio/content/examples/testing/src/app/shared/highlight.directive.spec.ts

@@ -3,7 +3,6 @@ import { ComponentFixture, TestBed } from '@angular/core/testing';
 import { By } from '@angular/platform-browser';
 
 import { HighlightDirective } from './highlight.directive';
-import { newEvent } from '../../testing';
 
 // #docregion test-component
 @Component({
@@ -59,9 +58,12 @@ describe('HighlightDirective', () => {
     const input = des[2].nativeElement as HTMLInputElement;
     expect(input.style.backgroundColor).toBe('cyan', 'initial backgroundColor');
 
-    // dispatch a DOM event so that Angular responds to the input value change.
     input.value = 'green';
-    input.dispatchEvent(newEvent('input'));
+
+    // Dispatch a DOM event so that Angular responds to the input value change.
+    // In older browsers, such as IE, you might need a CustomEvent instead. See
+    // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+    input.dispatchEvent(new Event('input'));
     fixture.detectChanges();
 
     expect(input.style.backgroundColor).toBe('green', 'changed backgroundColor');

aio/content/examples/testing/src/testing/index.ts

@@ -14,18 +14,6 @@ export function advance(f: ComponentFixture<any>): void {
   f.detectChanges();
 }
 
-/**
- * Create custom DOM event the old fashioned way
- *
- * https://developer.mozilla.org/en-US/docs/Web/API/Event/initEvent
- * Although officially deprecated, some browsers (phantom) don't accept the preferred "new Event(eventName)"
- */
-export function newEvent(eventName: string, bubbles = false, cancelable = false) {
-  const evt = document.createEvent('CustomEvent');  // MUST be 'CustomEvent'
-  evt.initCustomEvent(eventName, bubbles, cancelable, null);
-  return evt;
-}
-
 // See https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button
 // #docregion click-event
 /** Button events to pass to `DebugElement.triggerEventHandler` for RouterLink event handler */

aio/content/examples/tslint.json

@@ -1,5 +1,8 @@
 {
   "extends": "tslint:recommended",
+  "rulesDirectory": [
+    "codelyzer"
+  ],
   "rules": {
     "align": {
       "options": [
@@ -13,22 +16,6 @@
     "deprecation": {
       "severity": "warning"
     },
-    "component-class-suffix": true,
-    "component-selector": [
-      true,
-      "element",
-      // TODO: Fix the code and change the prefix to `"app"` (or whatever makes sense).
-      "",
-      "kebab-case"
-    ],
-    "contextual-lifecycle": true,
-    "directive-class-suffix": true,
-    "directive-selector": [
-      true,
-      "attribute",
-      ["app", "toh"],
-      "camelCase"
-    ],
     "eofline": true,
     "import-blacklist": [
       true,
@@ -56,6 +43,8 @@
         ]
       }
     ],
+    // TODO(gkalpak): Fix the code and enable this.
+    // "no-any": true,
     "no-console": [
       true,
       "debug",
@@ -95,6 +84,11 @@
         "named": "never"
       }
     },
+    // TODO(gkalpak): Fix the code and enable this.
+    // "typedef": [
+    //   true,
+    //   "call-signature"
+    // ],
     "typedef-whitespace": {
       "options": [
         {
@@ -130,6 +124,9 @@
         "check-typecast"
       ]
     },
+    "component-class-suffix": true,
+    "contextual-lifecycle": true,
+    "directive-class-suffix": true,
     "no-conflicting-lifecycle": true,
     "no-host-metadata-property": true,
     "no-input-rename": true,
@@ -141,9 +138,19 @@
     "template-banana-in-box": true,
     "template-no-negated-async": true,
     "use-lifecycle-interface": true,
-    "use-pipe-transform-interface": true
-  },
-  "rulesDirectory": [
-    "codelyzer"
-  ]
+    "use-pipe-transform-interface": true,
+    "directive-selector": [
+      true,
+      "attribute",
+      ["app", "toh"],
+      "camelCase"
+    ],
+    "component-selector": [
+      true,
+      "element",
+      // TODO: Fix the code and change the prefix to `"app"` (or whatever makes sense).
+      "",
+      "kebab-case"
+    ]
+  }
 }

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

@@ -1,9 +1,7 @@
 import * as angular from 'angular';
 import 'angular-route';
 
-const appName = 'myApp';
-
-angular.module(appName, [
+const appModule = angular.module('myApp', [
   'ngRoute'
 ])
 .config(['$routeProvider', '$locationProvider',
@@ -25,5 +23,5 @@ angular.module(appName, [
 );
 
 export function bootstrap(el: HTMLElement) {
-  return angular.bootstrap(el,  [appName]);
+  return angular.bootstrap(el,  [appModule.name]);
 }

aio/content/guide/architecture-services.md

@@ -95,7 +95,7 @@ or in the `@NgModule()` or `@Component()` metadata
    Registering the provider in the `@Injectable()` metadata also allows Angular to optimize an app
    by removing the service from the compiled app if it isn't used.
 
-* When you register a provider with a [specific NgModule](guide/architecture-modules), the same instance of a service is available to all components in that NgModule. To register at this level, use the `providers` property of the `@NgModule()` decorator,
+* When you register a provider with a [specific NgModule](guide/architecture-modules), the same instance of a service is available to all components in that NgModule. To register at this level, use the `providers` property of the `@NgModule()` decorator.
 
    ```
    @NgModule({

aio/content/guide/bootstrapping.md

@@ -18,8 +18,6 @@ When you use the [Angular CLI](cli) command `ng new` to generate an app, the def
 /* JavaScript imports */
 import { BrowserModule } from '@angular/platform-browser';
 import { NgModule } from '@angular/core';
-import { FormsModule } from '@angular/forms';
-import { HttpClientModule } from '@angular/common/http';
 
 import { AppComponent } from './app.component';
 
@@ -29,9 +27,7 @@ import { AppComponent } from './app.component';
     AppComponent
   ],
   imports: [
-    BrowserModule,
-    FormsModule,
-    HttpClientModule
+    BrowserModule
   ],
   providers: [],
   bootstrap: [AppComponent]
@@ -120,9 +116,6 @@ Now you could use your `ItemDirective` in a component. This example uses `AppMod
 
 Remember, components, directives, and pipes belong to one module only. You only need to declare them once in your app because you share them by importing the necessary modules. This saves you time and helps keep your app lean.
 
-
-
-
 {@a imports}
 
 ## The `imports` array
@@ -130,6 +123,12 @@ Remember, components, directives, and pipes belong to one module only. You only
 The module's `imports` array appears exclusively in the `@NgModule` metadata object.
 It tells Angular about other NgModules that this particular module needs to function properly.
 
+<code-example
+    path="bootstrapping/src/app/app.module.ts"
+    region="imports"
+    header="src/app/app.module.ts (excerpt)">
+</code-example>
+
 This list of modules are those that export components, directives, or pipes
 that component templates in this module reference. In this case, the component is
 `AppComponent`, which references components, directives, or pipes in `BrowserModule`,
@@ -138,6 +137,8 @@ A component template can reference another component, directive,
 or pipe when the referenced class is declared in this module or
 the class was imported from another module.
 
+
+
 {@a bootstrap-array}
 
 ## The `providers` array

aio/content/guide/component-styles.md

@@ -119,7 +119,7 @@ The `/deep/` combinator also has the aliases `>>>`, and `::ng-deep`.
 
 Use `/deep/`, `>>>` and `::ng-deep` only with *emulated* view encapsulation.
 Emulated is the default and most commonly used view encapsulation. For more information, see the
-[Controlling view encapsulation](guide/component-styles#view-encapsulation) section.
+[View Encapsulation](guide/view-encapsulation) section.
 
 </div>
 
@@ -267,89 +267,3 @@ as explained in the [CLI wiki](https://github.com/angular/angular-cli/wiki/stori
 Style strings added to the `@Component.styles` array _must be written in CSS_ because the CLI cannot apply a preprocessor to inline styles.
 
 </div>
-
-{@a view-encapsulation}
-
-## View encapsulation
-
-As discussed earlier, component CSS styles are encapsulated into the component's view and don't
-affect the rest of the application.
-
-To control how this encapsulation happens on a *per
-component* basis, you can set the *view encapsulation mode* in the component metadata.
-Choose from the following modes:
-
-* `ShadowDom` view encapsulation uses the browser's native shadow DOM implementation (see
-  [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Shadow_DOM)
-  on the [MDN](https://developer.mozilla.org) site)
-  to attach a shadow DOM to the component's host element, and then puts the component
-  view inside that shadow DOM. The component's styles are included within the shadow DOM.
-
-* `Native` view encapsulation uses a now deprecated version of the browser's native shadow DOM implementation - [learn about the changes](https://hayato.io/2016/shadowdomv1/).
-
-* `Emulated` view encapsulation (the default) emulates the behavior of shadow DOM by preprocessing
-  (and renaming) the CSS code to effectively scope the CSS to the component's view.
-  For details, see [Inspecting generated CSS](guide/component-styles#inspect-generated-css) below.
-
-* `None` means that Angular does no view encapsulation.
-  Angular adds the CSS to the global styles.
-  The scoping rules, isolations, and protections discussed earlier don't apply.
-  This is essentially the same as pasting the component's styles into the HTML.
-
-To set the components encapsulation mode, use the `encapsulation` property in the component metadata:
-
-<code-example path="component-styles/src/app/quest-summary.component.ts" region="encapsulation.native" header="src/app/quest-summary.component.ts"></code-example>
-
-`ShadowDom` view encapsulation only works on browsers that have native support
-for shadow DOM (see [Shadow DOM v1](https://caniuse.com/#feat=shadowdomv1) on the
-[Can I use](http://caniuse.com) site). The support is still limited,
-which is why `Emulated` view encapsulation is the default mode and recommended
-in most cases.
-
-{@a inspect-generated-css}
-
-## Inspecting generated CSS
-
-When using emulated view encapsulation, Angular preprocesses
-all component styles so that they approximate the standard shadow CSS scoping rules.
-
-In the DOM of a running Angular application with emulated view
-encapsulation enabled, each DOM element has some extra attributes
-attached to it:
-
-<code-example format="">
-  &lt;hero-details _nghost-pmm-5>
-    &lt;h2 _ngcontent-pmm-5>Mister Fantastic&lt;/h2>
-    &lt;hero-team _ngcontent-pmm-5 _nghost-pmm-6>
-      &lt;h3 _ngcontent-pmm-6>Team&lt;/h3>
-    &lt;/hero-team>
-  &lt;/hero-detail>
-
-</code-example>
-
-There are two kinds of generated attributes:
-
-* An element that would be a shadow DOM host in native encapsulation has a
-  generated `_nghost` attribute. This is typically the case for component host elements.
-* An element within a component's view has a `_ngcontent` attribute
-that identifies to which host's emulated shadow DOM this element belongs.
-
-The exact values of these attributes aren't important. They are automatically
-generated and you never refer to them in application code. But they are targeted
-by the generated component styles, which are in the `<head>` section of the DOM:
-
-<code-example format="">
-  [_nghost-pmm-5] {
-    display: block;
-    border: 1px solid black;
-  }
-
-  h3[_ngcontent-pmm-6] {
-    background-color: white;
-    border: 1px solid #777;
-  }
-</code-example>
-
-These styles are post-processed so that each selector is augmented
-with `_nghost` or `_ngcontent` attribute selectors.
-These extra selectors enable the scoping rules described in this page.

aio/content/guide/creating-libraries.md

@@ -156,7 +156,7 @@ The library must be rebuilt on every change.
 When linking a library, make sure that the build step runs in watch mode, and that the library's `package.json` configuration points at the correct entry points.
 For example, `main` should point at a JavaScript file, not a TypeScript file.
 
-## Use TypeScript path mapping for peer dependencies
+### Use TypeScript path mapping for peer dependencies
 
 Angular libraries should list all `@angular/*` dependencies as peer dependencies.
 This ensures that when modules ask for Angular, they all get the exact same module.

aio/content/guide/deployment.md

@@ -387,7 +387,7 @@ List the generated bundles in the `dist/` folder.
 
 <code-example language="none" class="code-shell">
 
-  ls dist/*.bundle.js
+  ls dist/*.js
 
 </code-example>
 
@@ -396,7 +396,7 @@ The following example displays the graph for the _main_ bundle.
 
 <code-example language="none" class="code-shell">
 
-  node_modules/.bin/source-map-explorer dist/main.*.bundle.js
+  node_modules/.bin/source-map-explorer dist/main*
 
 </code-example>
 

aio/content/guide/deprecations.md

@@ -603,18 +603,6 @@ In practical terms, the `package.json` of all `@angular` packages has changed in
 
 For more information about the npm package format, see the [Angular Package Format spec](https://goo.gl/jB3GVv).
 
-{@a removed}
-## Removed APIs
-
-The following APIs have been removed starting with version 10.0.0*:
-
-| Package          | API            | Replacement | Notes |
-| ---------------- | -------------- | ----------- | ----- |
-| `@angular/core`  | Undecorated base classes that use Angular features | Add Angular decorator | See [migration guide](guide/migration-undecorated-classes) for more info |
-| `@angular/core`  | `ModuleWithProviders` without a generic             | `ModuleWithProviders` with a generic | See [migration guide](guide/migration-module-with-providers) for more info |
-
-*To see APIs removed in version 9, check out this guide on the [version 9 docs site](https://v9.angular.io/guide/deprecations#removed).
-
 {@a style-sanitization}
 ### Style Sanitization for `[style]` and `[style.prop]` bindings
 Angular used to sanitize `[style]` and `[style.prop]` bindings to prevent malicious code from being inserted through `javascript:` expressions in CSS `url()` entries. However, most modern browsers no longer support the usage of these expressions, so sanitization was only maintained for the sake of IE 6 and 7. Given that Angular does not support either IE 6 or 7 and sanitization has a performance cost, we will no longer sanitize style bindings as of version 10 of Angular.

aio/content/guide/pipes.md

@@ -397,7 +397,7 @@ The following code example binds an observable of message strings
 ## Caching HTTP requests
 
 To [communicate with backend services using HTTP](/guide/http "Communicating with backend services using HTTP"), the `HttpClient` service uses observables and offers the `HTTPClient.get()` method to fetch data from a server.
-The aynchronous method sends an HTTP request, and returns an observable that emits the requested data for the response.
+The asynchronous method sends an HTTP request, and returns an observable that emits the requested data for the response.
 
 As shown in the previous section, you can use the impure `AsyncPipe` to accept an observable as input and subscribe to the input automatically.
 You can also create an impure pipe to make and cache an HTTP request.

aio/content/guide/rx-library.md

@@ -15,11 +15,11 @@ RxJS provides an implementation of the `Observable` type, which is needed until
 RxJS offers a number of functions that can be used to create new observables. These functions can simplify the process of creating observables from things such as events, timers, promises, and so on. For example:
 
 
-<code-example path="rx-library/src/simple-creation.ts" region="promise" header="Create an observable from a promise"></code-example>
+<code-example path="rx-library/src/simple-creation.1.ts" region="promise" header="Create an observable from a promise"></code-example>
 
-<code-example path="rx-library/src/simple-creation.ts" region="interval" header="Create an observable from a counter"></code-example>
+<code-example path="rx-library/src/simple-creation.2.ts" region="interval" header="Create an observable from a counter"></code-example>
 
-<code-example path="rx-library/src/simple-creation.ts" region="event" header="Create an observable from an event"></code-example>
+<code-example path="rx-library/src/simple-creation.3.ts" region="event" header="Create an observable from an event"></code-example>
 
 <code-example path="rx-library/src/simple-creation.ts" region="ajax" header="Create an observable that creates an AJAX request"></code-example>
 

aio/content/guide/template-statements.md

@@ -1,7 +1,7 @@
 # Template statements
 
-A template **statement** responds to an **event** raised by a binding target
-such as an element, component, or directive.
+Template statements are methods or properties that you can use in your HTML to respond to user events.
+With template statements, your application can engage users through actions such as displaying dynamic content or submitting forms.
 
 <div class="alert is-helpful">
 
@@ -10,24 +10,30 @@ the syntax and code snippets in this guide.
 
 </div>
 
-The following template statement appears in quotes to the right of the `=`&nbsp;symbol as in `(event)="statement"`.
+In the following example, the template statement `deleteHero()` appears in quotes to the right of the `=`&nbsp;symbol as in `(event)="statement"`.
 
 <code-example path="template-syntax/src/app/app.component.html" region="context-component-statement" header="src/app/app.component.html"></code-example>
 
-A template statement *has a side effect*.
-That's the whole point of an event.
-It's how you update application state from user action.
+When the user clicks the **Delete hero** button, Angular calls the `deleteHero()` function in the component class.
 
-Responding to events is the other side of Angular's "unidirectional data flow".
-You're free to change anything, anywhere, during this turn of the event loop.
+You can use template statements with elements, components, or directives in response to events.
 
-Like template expressions, template *statements* use a language that looks like JavaScript.
-The template statement parser differs from the template expression parser and
-specifically supports both basic assignment (`=`) and chaining expressions with <code>;</code>.
+<div class="alert is-helpful">
 
-However, certain JavaScript and template expression syntax is not allowed:
+Responding to events is an aspect of Angular's [unidirectional data flow](guide/glossary#unidirectional-data-flow).
+You can change anything in your application during a single event loop.
 
-* <code>new</code>
+</div>
+
+## Syntax
+
+Like [template expressions](guide/interpolation), template statements use a language that looks like JavaScript.
+However, the parser for template statements differs from the parser for template expressions.
+In addition, the template statements parser specifically supports both basic assignment, `=`, and chaining expressions with semicolons, `;`.
+
+The following JavaScript and template expression syntax is not allowed:
+
+* `new`
 * increment and decrement operators, `++` and `--`
 * operator assignment, such as `+=` and `-=`
 * the bitwise operators, such as `|` and `&`
@@ -35,31 +41,32 @@ However, certain JavaScript and template expression syntax is not allowed:
 
 ## Statement context
 
-As with expressions, statements can refer only to what's in the statement context
-such as an event handling method of the component instance.
+Statements have a context&mdash;a particular part of the application to which the statement belongs.
 
-The *statement context* is typically the component instance.
-The *deleteHero* in `(click)="deleteHero()"` is a method of the data-bound component.
+Statements can refer only to what's in the statement context, which is typically the component instance.
+For example, `deleteHero()` of `(click)="deleteHero()"` is a method of the component in the following snippet.
 
 <code-example path="template-syntax/src/app/app.component.html" region="context-component-statement" header="src/app/app.component.html"></code-example>
 
 The statement context may also refer to properties of the template's own context.
-In the following examples, the template `$event` object,
-a [template input variable](guide/built-in-directives#template-input-variable) (`let hero`),
-and a [template reference variable](guide/template-reference-variables) (`#heroForm`)
-are passed to an event handling method of the component.
+In the following example, the component's event handling method, `onSave()` takes the template's own `$event` object as an argument.
+On the next two lines, the `deleteHero()` method takes a [template input variable](guide/built-in-directives#template-input-variable), `hero`, and `onSubmit()` takes a [template reference variable](guide/template-reference-variables), `#heroForm`.
 
 <code-example path="template-syntax/src/app/app.component.html" region="context-var-statement" header="src/app/app.component.html"></code-example>
 
+In this example, the context of the `$event` object, `hero`, and `#heroForm` is the template.
+
 Template context names take precedence over component context names.
-In `deleteHero(hero)` above, the `hero` is the template input variable,
-not the component's `hero` property.
+In the preceding `deleteHero(hero)`, the `hero` is the template input variable, not the component's `hero` property.
 
-## Statement guidelines
+## Statement best practices
 
-Template statements cannot refer to anything in the global namespace. They
-can't refer to `window` or `document`.
-They can't call `console.log` or `Math.max`.
+* **Conciseness**
 
-As with expressions, avoid writing complex template statements.
-A method call or simple property assignment should be the norm.
+  Keep template statements minimal by using method calls or basic property assignments.
+
+* **Work within the context**
+
+  The context of a template statement can be the component class instance or the template.
+  Because of this, template statements cannot refer to anything in the global namespace such as `window` or `document`.
+  For example, template statements can't call `console.log()` or `Math.max()`.

aio/content/guide/upgrade.md

@@ -479,6 +479,15 @@ using the `downgradeComponent()` method. The result is an AngularJS
 <code-example path="upgrade-module/src/app/downgrade-static/app.module.ts" region="downgradecomponent" header="app.module.ts">
 </code-example>
 
+<div class="alert is-helpful">
+
+By default, Angular change detection will also run on the component for every
+AngularJS `$digest` cycle. If you wish to only have change detection run when
+the inputs change, you can set `propagateDigest` to `false` when calling
+`downgradeComponent()`.
+
+</div>
+
 Because `HeroDetailComponent` is an Angular component, you must also add it to the
 `declarations` in the `AppModule`.
 

aio/content/guide/user-input.md

@@ -324,5 +324,5 @@ These techniques are useful for small-scale demonstrations, but they
 quickly become verbose and clumsy when handling large amounts of user input.
 Two-way data binding is a more elegant and compact way to move
 values between data entry fields and model properties.
-The next page, `Forms`, explains how to write
+The [`Forms`](guide/forms-overview) page explains how to write
 two-way bindings with `NgModel`.

aio/content/guide/using-libraries.md

@@ -32,7 +32,7 @@ To do this:
 
 1. Create a `typings.d.ts` file in your `src/` folder. This file is automatically included as global type definition.
 
-2. Add the following code in `src/typings.d.ts`.
+2. Add the following code in `src/typings.d.ts`:
 
 ```
 declare module 'host' {
@@ -45,7 +45,7 @@ declare module 'host' {
 }
 ```
 
-3. In the component or file that uses the library, add the following code.
+3. In the component or file that uses the library, add the following code:
 
 ```
 import * as host from 'host';
@@ -129,7 +129,7 @@ interface JQuery {
 }
 ```
 
-If don't add the interface for the script-defined extension, your IDE shows an error:
+If you don't add the interface for the script-defined extension, your IDE shows an error:
 
 ```
 [TS][Error] Property 'myPlugin' does not exist on type 'JQuery'

aio/content/guide/view-encapsulation.md

@@ -0,0 +1,83 @@
+# View encapsulation
+
+In Angular, component CSS styles are encapsulated into the component's view and don't
+affect the rest of the application.
+
+To control how this encapsulation happens on a *per
+component* basis, you can set the *view encapsulation mode* in the component metadata.
+Choose from the following modes:
+
+* `ShadowDom` view encapsulation uses the browser's native shadow DOM implementation (see
+  [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Shadow_DOM)
+  on the [MDN](https://developer.mozilla.org) site)
+  to attach a shadow DOM to the component's host element, and then puts the component
+  view inside that shadow DOM. The component's styles are included within the shadow DOM.
+
+* `Native` view encapsulation uses a now deprecated version of the browser's native shadow DOM implementation - [learn about the changes](https://hayato.io/2016/shadowdomv1/).
+
+* `Emulated` view encapsulation (the default) emulates the behavior of shadow DOM by preprocessing
+  (and renaming) the CSS code to effectively scope the CSS to the component's view.
+  For details, see [Inspecting generated CSS](guide/view-encapsulation#inspect-generated-css) below.
+
+* `None` means that Angular does no view encapsulation.
+  Angular adds the CSS to the global styles.
+  The scoping rules, isolations, and protections discussed earlier don't apply.
+  This is essentially the same as pasting the component's styles into the HTML.
+
+To set the components encapsulation mode, use the `encapsulation` property in the component metadata:
+
+<code-example path="component-styles/src/app/quest-summary.component.ts" region="encapsulation.native" header="src/app/quest-summary.component.ts"></code-example>
+
+`ShadowDom` view encapsulation only works on browsers that have native support
+for shadow DOM (see [Shadow DOM v1](https://caniuse.com/#feat=shadowdomv1) on the
+[Can I use](http://caniuse.com) site). The support is still limited,
+which is why `Emulated` view encapsulation is the default mode and recommended
+in most cases.
+
+{@a inspect-generated-css}
+
+## Inspecting generated CSS
+
+When using emulated view encapsulation, Angular preprocesses
+all component styles so that they approximate the standard shadow CSS scoping rules.
+
+In the DOM of a running Angular application with emulated view
+encapsulation enabled, each DOM element has some extra attributes
+attached to it:
+
+<code-example format="">
+  &lt;hero-details _nghost-pmm-5>
+    &lt;h2 _ngcontent-pmm-5>Mister Fantastic&lt;/h2>
+    &lt;hero-team _ngcontent-pmm-5 _nghost-pmm-6>
+      &lt;h3 _ngcontent-pmm-6>Team&lt;/h3>
+    &lt;/hero-team>
+  &lt;/hero-detail>
+
+</code-example>
+
+There are two kinds of generated attributes:
+
+* An element that would be a shadow DOM host in native encapsulation has a
+  generated `_nghost` attribute. This is typically the case for component host elements.
+* An element within a component's view has a `_ngcontent` attribute
+that identifies to which host's emulated shadow DOM this element belongs.
+
+The exact values of these attributes aren't important. They are automatically
+generated and you never refer to them in application code. But they are targeted
+by the generated component styles, which are in the `<head>` section of the DOM:
+
+<code-example format="">
+  [_nghost-pmm-5] {
+    display: block;
+    border: 1px solid black;
+  }
+
+  h3[_ngcontent-pmm-6] {
+    background-color: white;
+    border: 1px solid #777;
+  }
+</code-example>
+
+These styles are post-processed so that each selector is augmented
+with `_nghost` or `_ngcontent` attribute selectors.
+These extra selectors enable the scoping rules described in this page.

aio/content/marketing/analytics.md

@@ -12,7 +12,7 @@ include the following information:
 - Node and Angular CLI version (local version only).
 - How long each command took to initialize and execute.
 - Command name that was run.
-- For Schematics commands (add, generate, new and update), a list of whitelisted flags.
+- For Schematics commands (add, generate, new and update), a list of selected flags.
 - For build commands (build, serve), the number and size of bundles (initial and lazy),
   compilation units, the time it took to build and rebuild, and basic Angular-specific
   API usage.

aio/content/marketing/docs.md

@@ -46,7 +46,7 @@ Most Angular code can be written with just the latest JavaScript, using [types](
 
 <h3>You can sit with us!</h3>
 
-We want to hear from you. [Report problems or submit suggestions for future docs.](https://github.com/angular/angular/issues/new/choose "Angular GitHub repository new issue form")
+We want to hear from you. [Report problems or submit suggestions for future docs](https://github.com/angular/angular/issues/new/choose "Angular GitHub repository new issue form").
 
 Contribute to Angular docs by creating
 [pull requests](https://github.com/angular/angular/pulls "Angular Github pull requests")

aio/content/marketing/events.html

@@ -3,162 +3,5 @@
 </header>
 
 <article class="events-container">
-  <p>Where we'll be presenting:</p>
-  <table class="is-full-width">
-    <thead>
-      <tr>
-        <th>Event</th>
-        <th>Location</th>
-        <th>Date</th>
-      </tr>
-    </thead>
-    <tbody>
-    </tbody>
-  </table>
-
-  <p>Where we already presented:</p>
-  <table class="is-full-width">
-    <thead>
-      <tr>
-        <th>Event</th>
-        <th>Location</th>
-        <th>Date</th>
-      </tr>
-    </thead>
-    <tbody>
-      <!-- ng-vikings 2020 -->
-      <tr>
-        <th><a href="https://ngvikings.org/" title="ngVikings">ngVikings</a></th>
-        <td>Oslo, Norway</td>
-        <td>May 25-26 conference, 27 workshops, 2020</td>
-      </tr>
-      <!-- ng-conf 2020 -->
-      <tr>
-        <th><a href="https://ng-conf.org/" title="ng-conf">ng-conf</a></th>
-        <td>Salt Lake City, Utah</td>
-        <td>April 1-3, 2020</td>
-      </tr>
-      <!-- ngIndia 2020 -->
-      <tr>
-        <th><a href="https://www.ng-ind.com/" title="ngIndia">ngIndia</a></th>
-        <td>Delhi, India</td>
-        <td>Feb 29, 2020</td>
-      </tr>
-      <!-- ReactiveConf 2019 -->
-      <tr>
-        <th><a href="https://reactiveconf.com/" title="ReactiveConf">ReactiveConf</a></th>
-        <td>Prague, Czech Republic</td>
-        <td>October 30 - November 1, 2019</td>
-      </tr>
-      <!-- NG Rome 2019-->
-      <tr>
-        <th>
-          <a href="https://ngrome.io" title="NG Rome MMXIX - The Italian Angular Conference">NG Rome MMXIX</a>
-        </th>
-        <td>Rome, Italy</td>
-        <td>Oct 6th workshops, 7th conference, 2019</td>
-      </tr>
-      <!-- AngularConnect 2019-->
-      <tr>
-        <th><a href="https://www.angularconnect.com/?utm_source=angular.io&utm_medium=referral"
-            title="AngularConnect">AngularConnect</a></th>
-        <td>London, UK</td>
-        <td>September 19-20, 2019</td>
-      </tr>
-      <!-- NG-DE 2019-->
-      <tr>
-        <th><a href="https://ng-de.org/" title="NG-DE">NG-DE</a></th>
-        <td>Berlin, Germany</td>
-        <td>August 29th workshops, 30-31 conference, 2019</td>
-      </tr>
-      <!-- ngJapan-->
-      <tr>
-        <th><a href="https://ngjapan.org" title="ng-japan">ng-japan</a></th>
-        <td>Tokyo, Japan</td>
-        <td>July 13, 2019</td>
-      </tr>
-      <!-- ngVikings 2019-->
-      <tr>
-        <th><a href="https://ngvikings.org/" title="ngVikings">ngVikings</a></th>
-        <td>Copenhagen, Denmark</td>
-        <td>May 26 (workshops), 27-28 (conference), 2019</td>
-      </tr>
-      <!-- ng-conf 2019-->
-      <tr>
-        <th><a href="https://ng-conf.org/" title="ng-conf">ng-conf</a></th>
-        <td>Salt Lake City, Utah</td>
-        <td>May 1-3, 2019</td>
-      </tr>
-      <!-- ng-India 2019-->
-      <tr>
-        <th><a href="https://www.ng-ind.com/" title="ng-India">ng-India</a></th>
-        <td>Gurgaon, India</td>
-        <td>February 23, 2019</td>
-      </tr>
-      <!-- ngAtlanta 2019 -->
-      <tr>
-        <th><a href="https://ng-atl.org/" title="ngAtlanta">ngAtlanta</a></th>
-        <td>Atlanta, Georgia</td>
-        <td>January 9-12, 2019</td>
-      </tr>
-      <!-- AngularConnect-->
-      <tr>
-        <th>
-          <a href="https://past.angularconnect.com/2018" title="AngularConnect">AngularConnect</a>
-        </th>
-        <td>London, United Kingdom</td>
-        <td>November 5-7, 2018</td>
-      </tr>
-      <!-- ReactiveConf -->
-      <tr>
-        <th><a href="https://reactiveconf.com/" title="ReactiveConf">ReactiveConf</a></th>
-        <td>Prague, Czech Republic</td>
-        <td>October 29-31, 2018</td>
-      </tr>
-      <!-- AngularMix -->
-      <tr>
-        <th><a href="https://angularmix.com/" title="AngularMix">AngularMix</a></th>
-        <td>Orlando, Florida</td>
-        <td>October 10-12, 2018</td>
-      </tr>
-      <!-- Angular Conf Australia-->
-      <tr>
-        <th>
-          <a href="https://www.angularconf.com.au/" title="Angular Conf Australia">Angular Conf Australia</a>
-        </th>
-        <td>Melbourne, Australia</td>
-        <td>Jun 22, 2018</td>
-      </tr>
-      <!-- ngJapan-->
-      <tr>
-        <th><a href="https://ngjapan.org/en.html" title="ng-japan">ng-japan</a></th>
-        <td>Tokyo, Japan</td>
-        <td>Jun 16, 2018</td>
-      </tr>
-      <!-- WeRDevs-->
-      <tr>
-        <th><a href="https://www.wearedevelopers.com/" title="WeAreDevs">WeAreDevelopers</a></th>
-        <td>Vienna, Austria</td>
-        <td>May 16-18, 2018</td>
-      </tr>
-      <!-- ngconf 2018-->
-      <tr>
-        <th><a href="https://www.ng-conf.org/" title="ng-conf">ng-conf</a></th>
-        <td>Salt Lake City, Utah</td>
-        <td>April 18-20, 2018</td>
-      </tr>
-      <!-- ngVikings-->
-      <tr>
-        <th><a href="https://ngvikings.org/" title="ngVikings">ngVikings</a></th>
-        <td>Helsinki, Finland</td>
-        <td>March 1-2, 2018</td>
-      </tr>
-      <!-- ngAtlanta-->
-      <tr>
-        <th><a href="http://ng-atl.org/" title="ngAtlanta">ngAtlanta</a></th>
-        <td>Atlanta, Georgia</td>
-        <td>January 30, 2018</td>
-      </tr>
-    </tbody>
-  </table>
+  <aio-events></aio-events>
 </article>

aio/content/marketing/events.json

@@ -0,0 +1,245 @@
+[
+  {
+    "name": "ng-china",
+    "location": "Online",
+    "linkUrl": "https://ng-china.org/",
+    "date": {
+      "start": "2020-11-21",
+      "end": "2020-11-22"
+    }
+  },
+  {
+    "name": "EnterpriseNG",
+    "location": "Online",
+    "linkUrl": "https://www.ng-conf.org/",
+    "date": {
+      "start": "2020-11-19",
+      "end": "2020-11-20"
+    }
+  },
+  {
+    "name": "ngrome",
+    "location": "Online",
+    "linkUrl": "https://ngrome.io/",
+    "date": {
+      "start": "2020-10-20",
+      "end": "2020-10-20"
+    }
+  },
+  {
+    "name": "DevReach",
+    "location": "Online",
+    "linkUrl": "https://www.telerik.com/devreach/online/agenda-thursday#sessions",
+    "date": {
+      "start": "2020-10-19",
+      "end": "2020-10-23"
+    }
+  },
+  {
+    "name": "ngVikings",
+    "location": "Oslo, Norway",
+    "linkUrl": "https://ngvikings.org/",
+    "date": {
+      "start": "2020-05-25",
+      "end": "2020-05-26"
+    },
+    "workshopsDate": {
+      "start": "2020-05-27",
+      "end": "2020-05-27"
+    }
+  },
+  {
+    "name": "ng-conf",
+    "location": "Salt Lake City, Utah",
+    "linkUrl": "https://ng-conf.org/",
+    "date": {
+      "start": "2020-04-01",
+      "end": "2020-04-03"
+    }
+  },
+  {
+    "name": "ngIndia",
+    "location": "Delhi, India",
+    "linkUrl": "https://www.ng-ind.com/",
+    "date": {
+      "start": "2020-02-29",
+      "end": "2020-02-29"
+    }
+  },
+  {
+    "name": "ReactiveConf",
+    "location": "Prague, Czech Republic",
+    "linkUrl": "https://reactiveconf.com/",
+    "date": {
+      "start": "2019-10-30",
+      "end": "2019-11-01"
+    }
+  },
+  {
+    "name": "NG Rome MMXIX",
+    "location": "Rome, Italy",
+    "linkUrl": "https://ngrome.io",
+    "tooltip": "NG Rome MMXIX - The Italian Angular Conference",
+    "date": {
+      "start": "2019-10-07",
+      "end": "2019-10-07"
+    },
+    "workshopsDate": {
+      "start": "2019-10-06",
+      "end": "2019-10-06"
+    }
+  },
+  {
+    "name": "AngularConnect",
+    "location": "London, UK",
+    "linkUrl": "https://www.angularconnect.com/?utm_source=angular.io&utm_medium=referral",
+    "date": {
+      "start": "2019-09-19",
+      "end": "2019-09-20"
+    }
+  },
+  {
+    "name": "NG-DE",
+    "location": "Berlin, Germany",
+    "linkUrl": "https://ng-de.org/",
+    "date": {
+      "start": "2019-08-30",
+      "end": "2019-08-31"
+    },
+    "workshopsDate": {
+      "start": "2019-08-29",
+      "end": "2019-08-29"
+    }
+  },
+  {
+    "name": "ng-japan",
+    "location": "Tokyo, Japan",
+    "linkUrl": "https://ngjapan.org/",
+    "date": {
+      "start": "2019-07-13",
+      "end": "2019-07-13"
+    }
+  },
+  {
+    "name": "ngVikings",
+    "location": "Copenhagen, Denmark",
+    "linkUrl": "https://ngvikings.org/",
+    "date": {
+      "start": "2019-05-27",
+      "end": "2019-05-28"
+    },
+    "workshopsDate": {
+      "start": "2019-05-26",
+      "end": "2019-05-26"
+    }
+  },
+  {
+    "name": "ng-conf",
+    "location": "Salt Lake City, Utah",
+    "linkUrl": "https://ng-conf.org/",
+    "date": {
+      "start": "2019-05-01",
+      "end": "2019-05-03"
+    }
+  },
+  {
+    "name": "ng-India",
+    "location": "Gurgaon, India",
+    "linkUrl": "https://www.ng-ind.com/",
+    "date": {
+      "start": "2019-02-23",
+      "end": "2019-02-23"
+    }
+  },
+  {
+    "name": "ngAtlanta",
+    "location": "Atlanta, Georgia",
+    "linkUrl": "https://ng-atl.org/",
+    "date": {
+      "start": "2019-01-09",
+      "end": "2019-01-12"
+    }
+  },
+  {
+    "name": "AngularConnect",
+    "location": "London, United Kingdom",
+    "linkUrl": "https://past.angularconnect.com/2018",
+    "date": {
+      "start": "2018-11-05",
+      "end": "2018-11-07"
+    }
+  },
+  {
+    "name": "ReactiveConf",
+    "location": "Prague, Czech Republic",
+    "linkUrl": "https://reactiveconf.com/",
+    "date": {
+      "start": "2018-10-29",
+      "end": "2018-10-31"
+    }
+  },
+  {
+    "name": "AngularMix",
+    "location": "Orlando, Florida",
+    "linkUrl": "https://angularmix.com/",
+    "date": {
+      "start": "2018-10-10",
+      "end": "2018-10-12"
+    }
+  },
+  {
+    "name": "Angular Conf Australia",
+    "location": "Melbourne, Australia",
+    "linkUrl": "https://www.angularconf.com.au/",
+    "date": {
+      "start": "2018-06-22",
+      "end": "2018-06-22"
+    }
+  },
+  {
+    "name": "ng-japan",
+    "location": "Tokyo, Japan",
+    "linkUrl": "https://ngjapan.org/en.html",
+    "date": {
+      "start": "2018-06-16",
+      "end": "2018-06-16"
+    }
+  },
+  {
+    "name": "WeAreDevelopers",
+    "location": "Vienna, Austria",
+    "linkUrl": "https://www.wearedevelopers.com/",
+    "tooltip": "WeAreDevs",
+    "date": {
+      "start": "2018-05-16",
+      "end": "2018-05-18"
+    }
+  },
+  {
+    "name": "ng-conf",
+    "location": "Salt Lake City, Utah",
+    "linkUrl": "https://ng-conf.org/",
+    "date": {
+      "start": "2018-04-18",
+      "end": "2018-04-20"
+    }
+  },
+  {
+    "name": "ngVikings",
+    "location": "Helsinki, Finland",
+    "linkUrl": "https://ngvikings.org/",
+    "date": {
+      "start": "2018-03-01",
+      "end": "2018-03-02"
+    }
+  },
+  {
+    "name": "ngAtlanta",
+    "location": "Atlanta, Georgia",
+    "linkUrl": "https://ng-atl.org/",
+    "date": {
+      "start": "2018-01-30",
+      "end": "2018-01-30"
+    }
+  }
+]

aio/content/navigation.json

@@ -61,27 +61,27 @@
           "children": [
             {
               "url": "start",
-              "title": "A Sample App",
+              "title": "Getting started",
               "tooltip": "Take a look at Angular's component model, template syntax, and component communication."
             },
             {
               "url": "start/start-routing",
-              "title": "In-app Navigation",
+              "title": "Adding navigation",
               "tooltip": "Navigate among different page views using the browser's URL."
             },
             {
               "url": "start/start-data",
-              "title": "Manage Data",
+              "title": "Managing Data",
               "tooltip": "Use services and access external data via HTTP."
             },
             {
               "url": "start/start-forms",
-              "title": "Forms for User Input",
+              "title": "Using Forms for User Input",
               "tooltip": "Learn about fetching and managing data from users with forms."
             },
             {
               "url": "start/start-deployment",
-              "title": "Deployment",
+              "title": "Deploying an application",
               "tooltip": "Move to local development, or deploy your application to Firebase or your own server."
             }
           ]
@@ -116,6 +116,11 @@
               "title": "Component Lifecycle",
               "tooltip": "Angular calls lifecycle hook methods on directives and components as it creates, changes, and destroys them."
             },
+            { 
+              "url": "guide/view-encapsulation",
+              "title": "View Encapsulation",
+              "tooltip": "Describes how component CSS styles are encapsulated into a component's view."
+            },
             {
               "url": "guide/component-interaction",
               "title": "Component Interaction",

aio/content/start/index.md

@@ -1,4 +1,4 @@
-# Part 1: Getting started with a basic Angular app
+# Getting started with a basic Angular app
 
 Welcome to Angular!
 

aio/content/start/start-data.md

@@ -1,4 +1,4 @@
-# Try it: Manage data
+# Managing data
 
 At the end of [In-app Navigation](start/start-routing "Try it: In-app Navigation"), the online store application has a product catalog with two views: a product list and product details.
 Users can click on a product name from the list to see details in a new view, with a distinct URL, or route.

aio/content/start/start-deployment.md

@@ -1,4 +1,4 @@
-# Try it: Deployment
+# Deploying an application
 
 
 To deploy your application, you have to compile it, and then host the JavaScript, CSS, and HTML on a web server. Built Angular applications are very portable and can live in any environment or served by any technology, such as Node, Java, .NET, PHP, and many others.

aio/content/start/start-forms.md

@@ -1,4 +1,4 @@
-# Try it: Use forms for user input
+# Using forms for user input
 
 At the end of [Managing Data](start/start-data "Try it: Managing Data"), the online store application has a product catalog and a shopping cart.
 

aio/content/start/start-routing.md

@@ -1,4 +1,4 @@
-# In-app navigation
+# Adding navigation
 
 At the end of [part 1](start "Get started with a basic Angular app"), the online store application has a basic product catalog.
 The app doesn't have any variable states or navigation.

aio/package.json

@@ -23,7 +23,7 @@
     "build-local-with-viewengine": "yarn ~~build",
     "prebuild-local-with-viewengine-ci": "node scripts/switch-to-viewengine && yarn setup-local-ci",
     "build-local-with-viewengine-ci": "yarn ~~build --progress=false",
-    "extract-cli-command-docs": "node tools/transforms/cli-docs-package/extract-cli-commands.js ef770f1cb",
+    "extract-cli-command-docs": "node tools/transforms/cli-docs-package/extract-cli-commands.js ab97bc382",
     "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",
@@ -87,28 +87,27 @@
   },
   "private": true,
   "dependencies": {
-    "@angular/animations": "10.0.2",
-    "@angular/cdk": "10.0.1",
-    "@angular/common": "10.0.2",
-    "@angular/compiler": "10.0.2",
-    "@angular/core": "10.0.2",
-    "@angular/elements": "10.0.2",
-    "@angular/forms": "10.0.2",
-    "@angular/material": "10.0.1",
-    "@angular/platform-browser": "10.0.2",
-    "@angular/platform-browser-dynamic": "10.0.2",
-    "@angular/router": "10.0.2",
-    "@angular/service-worker": "10.0.2",
+    "@angular/animations": "10.1.3",
+    "@angular/cdk": "10.2.2",
+    "@angular/common": "10.1.3",
+    "@angular/compiler": "10.1.3",
+    "@angular/core": "10.1.3",
+    "@angular/elements": "10.1.3",
+    "@angular/forms": "10.1.3",
+    "@angular/material": "10.2.2",
+    "@angular/platform-browser": "10.1.3",
+    "@angular/platform-browser-dynamic": "10.1.3",
+    "@angular/router": "10.1.3",
+    "@angular/service-worker": "10.1.3",
     "@webcomponents/custom-elements": "1.2.1",
     "rxjs": "^6.5.3",
-    "tslib": "^1.10.0",
+    "tslib": "^2.0.0",
     "zone.js": "~0.10.3"
   },
   "devDependencies": {
-    "@angular-devkit/build-angular": "0.1000.1",
-    "@angular/cli": "10.0.1",
-    "@angular/compiler-cli": "10.0.2",
-    "@angular/language-service": "10.0.2",
+    "@angular-devkit/build-angular": "0.1001.3",
+    "@angular/cli": "10.1.3",
+    "@angular/compiler-cli": "10.1.3",
     "@types/jasmine": "^3.4.2",
     "@types/jasminewd2": "^2.0.8",
     "@types/lunr": "^2.3.2",
@@ -119,7 +118,7 @@
     "canonical-path": "1.0.0",
     "chalk": "^2.1.0",
     "cjson": "^0.5.0",
-    "codelyzer": "^6.0.0-next.1",
+    "codelyzer": "^6.0.0",
     "cross-spawn": "^5.1.0",
     "css-selector-parser": "^1.3.0",
     "dgeni": "^0.4.11",
@@ -136,8 +135,8 @@
     "html": "^1.0.0",
     "ignore": "^3.3.3",
     "image-size": "^0.5.1",
-    "jasmine": "^3.4.0",
-    "jasmine-core": "^3.4.0",
+    "jasmine": "~3.6.0",
+    "jasmine-core": "~3.6.0",
     "jasmine-spec-reporter": "~5.0.0",
     "jsdom": "^9.12.0",
     "json-schema-traverse": "^0.4.1",
@@ -145,7 +144,7 @@
     "karma": "~5.0.0",
     "karma-chrome-launcher": "^3.1.0",
     "karma-coverage-istanbul-reporter": "^2.1.0",
-    "karma-jasmine": "^3.1.1",
+    "karma-jasmine": "~4.0.0",
     "karma-jasmine-html-reporter": "^1.4.2",
     "light-server": "^2.6.2",
     "lighthouse": "6.1.0",
@@ -165,7 +164,7 @@
     "tree-kill": "^1.1.0",
     "ts-node": "^8.4.1",
     "tslint": "~6.1.0",
-    "typescript": "~3.9.5",
+    "typescript": "~4.0.2",
     "uglify-js": "^3.0.15",
     "unist-util-filter": "^0.2.1",
     "unist-util-source": "^1.0.1",

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

@@ -782,7 +782,7 @@ describe('AppComponent', () => {
         it('should grab focus when the / key is pressed', () => {
           const searchBox: SearchBoxComponent = fixture.debugElement.query(By.directive(SearchBoxComponent)).componentInstance;
           spyOn(searchBox, 'focus');
-          window.document.dispatchEvent(new KeyboardEvent('keyup', { 'key': '/' }));
+          window.document.dispatchEvent(new KeyboardEvent('keyup', { key: '/' }));
           fixture.detectChanges();
           expect(searchBox.focus).toHaveBeenCalled();
         });
@@ -791,7 +791,7 @@ describe('AppComponent', () => {
           const searchBox: SearchBoxComponent = fixture.debugElement.query(By.directive(SearchBoxComponent)).componentInstance;
           spyOn(searchBox, 'focus');
           component.showSearchResults = true;
-          window.document.dispatchEvent(new KeyboardEvent('keyup', { 'key': 'Escape' }));
+          window.document.dispatchEvent(new KeyboardEvent('keyup', { key: 'Escape' }));
           fixture.detectChanges();
           expect(searchBox.focus).toHaveBeenCalled();
         });
@@ -968,23 +968,23 @@ describe('AppComponent', () => {
 
         // Initially, `isTransitoning` is true.
         expect(component.isTransitioning).toBe(true);
-        expect(toolbar.classes['transitioning']).toBe(true);
+        expect(toolbar.classes.transitioning).toBe(true);
 
         triggerDocViewerEvent('docRendered');
         fixture.detectChanges();
         expect(component.isTransitioning).toBe(false);
-        expect(toolbar.classes['transitioning']).toBeFalsy();
+        expect(toolbar.classes.transitioning).toBeFalsy();
 
         // While a document is being rendered, `isTransitoning` is set to true.
         triggerDocViewerEvent('docReady');
         fixture.detectChanges();
         expect(component.isTransitioning).toBe(true);
-        expect(toolbar.classes['transitioning']).toBe(true);
+        expect(toolbar.classes.transitioning).toBe(true);
 
         triggerDocViewerEvent('docRendered');
         fixture.detectChanges();
         expect(component.isTransitioning).toBe(false);
-        expect(toolbar.classes['transitioning']).toBeFalsy();
+        expect(toolbar.classes.transitioning).toBeFalsy();
       });
 
       it('should update the sidenav state as soon as a new document is inserted (but not before)', () => {
@@ -1031,15 +1031,15 @@ describe('AppComponent', () => {
 
         navigateTo('guide/pipes');
         expect(component.pageId).toEqual('guide-pipes');
-        expect(container.properties['id']).toEqual('guide-pipes');
+        expect(container.properties.id).toEqual('guide-pipes');
 
         navigateTo('news');
         expect(component.pageId).toEqual('news');
-        expect(container.properties['id']).toEqual('news');
+        expect(container.properties.id).toEqual('news');
 
         navigateTo('');
         expect(component.pageId).toEqual('home');
-        expect(container.properties['id']).toEqual('home');
+        expect(container.properties.id).toEqual('home');
       });
 
       it('should not be affected by changes to the query', () => {
@@ -1050,7 +1050,7 @@ describe('AppComponent', () => {
         navigateTo('guide/other?search=http');
 
         expect(component.pageId).toEqual('guide-other');
-        expect(container.properties['id']).toEqual('guide-other');
+        expect(container.properties.id).toEqual('guide-other');
       });
     });
 
@@ -1125,7 +1125,7 @@ describe('AppComponent', () => {
 
       function checkHostClass(type: string, value: string) {
         const host = fixture.debugElement;
-        const classes: string = host.properties['className'];
+        const classes: string = host.properties.className;
         const classArray = classes.split(' ').filter(c => c.indexOf(`${type}-`) === 0);
         expect(classArray.length).toBeLessThanOrEqual(1, `"${classes}" should have only one class matching ${type}-*`);
         expect(classArray).toEqual([`${type}-${value}`], `"${classes}" should contain ${type}-${value}`);
@@ -1311,42 +1311,42 @@ class TestHttpClient {
 
   // tslint:disable:quotemark
   navJson = {
-    "TopBar": [
+    TopBar: [
       {
-        "url": "features",
-        "title": "Features"
+        url: 'features',
+        title: 'Features',
       },
       {
-        "url": "no-title",
-        "title": "No Title"
+        url: 'no-title',
+        title: 'No Title',
       },
     ],
-    "SideNav": [
+    SideNav: [
       {
-      "title": "Core",
-      "tooltip": "Learn the core capabilities of Angular",
-      "children": [
+        title: 'Core',
+        tooltip: 'Learn the core capabilities of Angular',
+        children: [
           {
-            "url": "guide/pipes",
-            "title": "Pipes",
-            "tooltip": "Pipes transform displayed values within a template."
+            url: 'guide/pipes',
+            title: 'Pipes',
+            tooltip: 'Pipes transform displayed values within a template.',
           },
           {
-            "url": "guide/bags",
-            "title": "Bags",
-            "tooltip": "Pack your bags for a code adventure."
-          }
-        ]
+            url: 'guide/bags',
+            title: 'Bags',
+            tooltip: 'Pack your bags for a code adventure.',
+          },
+        ],
       },
       {
-        "url": "api",
-        "title": "API",
-        "tooltip": "Details of the Angular classes and values."
-      }
+        url: 'api',
+        title: 'API',
+        tooltip: 'Details of the Angular classes and values.',
+      },
     ],
-    "docVersions": TestHttpClient.docVersions,
+    docVersions: TestHttpClient.docVersions,
 
-    "__versionInfo": TestHttpClient.versionInfo,
+    __versionInfo: TestHttpClient.versionInfo,
   };
 
   get(url: string) {

aio/src/app/app.component.ts

@@ -147,7 +147,7 @@ export class AppComponent implements OnInit {
     // Compute the version picker list from the current version and the versions in the navigation map
     combineLatest([
       this.navigationService.versionInfo,
-      this.navigationService.navigationViews.pipe(map(views => views['docVersions'])),
+      this.navigationService.navigationViews.pipe(map(views => views.docVersions)),
     ]).subscribe(([versionInfo, versions]) => {
       // TODO(pbd): consider whether we can lookup the stable and next versions from the internet
       const computedVersions: NavigationNode[] = [
@@ -167,10 +167,10 @@ export class AppComponent implements OnInit {
     });
 
     this.navigationService.navigationViews.subscribe(views => {
-      this.footerNodes = views['Footer'] || [];
-      this.sideNavNodes = views['SideNav'] || [];
-      this.topMenuNodes = views['TopBar'] || [];
-      this.topMenuNarrowNodes = views['TopBarNarrow'] || this.topMenuNodes;
+      this.footerNodes = views.Footer || [];
+      this.sideNavNodes = views.SideNav || [];
+      this.topMenuNodes = views.TopBar || [];
+      this.topMenuNarrowNodes = views.TopBarNarrow || this.topMenuNodes;
     });
 
     this.navigationService.versionInfo.subscribe(vi => this.versionInfo = vi);

aio/src/app/custom-elements/api/api-list.component.spec.ts

@@ -223,77 +223,77 @@ class TestApiService {
 // tslint:disable:quotemark
 const apiSections: ApiSection[] = [
   {
-    "name": "common",
-    "title": "common",
-    "path": "api/common",
-    "deprecated": false,
-    "items": [
+    name: 'common',
+    title: 'common',
+    path: 'api/common',
+    deprecated: false,
+    items: [
       {
-        "name": "class_1",
-        "title": "Class 1",
-        "path": "api/common/class_1",
-        "docType": "class",
-        "stability": "experimental",
-        "securityRisk": false,
+        name: 'class_1',
+        title: 'Class 1',
+        path: 'api/common/class_1',
+        docType: 'class',
+        stability: 'experimental',
+        securityRisk: false,
       },
       {
-        "name": "class_2",
-        "title": "Class 2",
-        "path": "api/common/class_2",
-        "docType": "class",
-        "stability": "stable",
-        "securityRisk": false,
+        name: 'class_2',
+        title: 'Class 2',
+        path: 'api/common/class_2',
+        docType: 'class',
+        stability: 'stable',
+        securityRisk: false,
       },
       {
-        "name": "directive_1",
-        "title": "Directive 1",
-        "path": "api/common/directive_1",
-        "docType": "directive",
-        "stability": "stable",
-        "securityRisk": true,
+        name: 'directive_1',
+        title: 'Directive 1',
+        path: 'api/common/directive_1',
+        docType: 'directive',
+        stability: 'stable',
+        securityRisk: true,
       },
       {
-        "name": "pipe_1",
-        "title": "Pipe 1",
-        "path": "api/common/pipe_1",
-        "docType": "pipe",
-        "stability": "stable",
-        "securityRisk": true,
+        name: 'pipe_1',
+        title: 'Pipe 1',
+        path: 'api/common/pipe_1',
+        docType: 'pipe',
+        stability: 'stable',
+        securityRisk: true,
       },
-    ]
+    ],
   },
   {
-    "name": "core",
-    "title": "core",
-    "path": "api/core",
-    "deprecated": false,
-    "items": [
+    name: 'core',
+    title: 'core',
+    path: 'api/core',
+    deprecated: false,
+    items: [
       {
-        "name": "class_3",
-        "title": "Class 3",
-        "path": "api/core/class_3",
-        "docType": "class",
-        "stability": "experimental",
-        "securityRisk": false,
+        name: 'class_3',
+        title: 'Class 3',
+        path: 'api/core/class_3',
+        docType: 'class',
+        stability: 'experimental',
+        securityRisk: false,
       },
       {
-        "name": "function_1",
-        "title": "Function 1",
-        "path": "api/core/function 1",
-        "docType": "function",
-        "stability": "deprecated",
-        "securityRisk": true,
+        name: 'function_1',
+        title: 'Function 1',
+        path: 'api/core/function 1',
+        docType: 'function',
+        stability: 'deprecated',
+        securityRisk: true,
       },
       {
-        "name": "const_1",
-        "title": "Const 1",
-        "path": "api/core/const_1",
-        "docType": "const",
-        "stability": "stable",
-        "securityRisk": false,
-      }
-    ]
-  }
+        name: 'const_1',
+        title: 'Const 1',
+        path: 'api/core/const_1',
+        docType: 'const',
+        stability: 'stable',
+        securityRisk: false,
+      },
+    ],
+  },
 ];
 
 function getApiSections() { return apiSections; }

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

@@ -67,7 +67,7 @@ export class ApiService implements OnDestroy {
   * API sections is an array of Angular top modules and metadata about their API documents (items).
   * Updates `sections` observable
   *
-  * @param {string} [src] - Name of the api list JSON file
+  * @param [src] - Name of the api list JSON file
   */
   fetchSections(src?: string) {
     // TODO: get URL by configuration?

aio/src/app/custom-elements/code/pretty-printer.service.ts

@@ -20,13 +20,13 @@ export class PrettyPrinter {
   }
 
   private getPrettyPrintOne(): Promise<PrettyPrintOne> {
-    const ppo = (window as any)['prettyPrintOne'];
+    const ppo = (window as any).prettyPrintOne;
     return ppo ? Promise.resolve(ppo) :
       // `prettyPrintOne` is not on `window`, which means `prettify.js` has not been loaded yet.
       // Import it; ad a side-effect it will add `prettyPrintOne` on `window`.
       import('assets/js/prettify.js' as any)
         .then(
-          () => (window as any)['prettyPrintOne'],
+          () => (window as any).prettyPrintOne,
           err => {
             const msg = `Cannot get prettify.js from server: ${err.message}`;
             this.logger.error(new Error(msg));
@@ -37,9 +37,9 @@ export class PrettyPrinter {
 
   /**
    * Format code snippet as HTML
-   * @param {string} code - the code snippet to format; should already be HTML encoded
-   * @param {string} [language] - The language of the code to render (could be javascript, html, typescript, etc)
-   * @param {string|number} [linenums] - Whether to display line numbers:
+   * @param code - the code snippet to format; should already be HTML encoded
+   * @param [language] - The language of the code to render (could be javascript, html, typescript, etc)
+   * @param [linenums] - Whether to display line numbers:
    *  - false: don't display
    *  - true: do display
    *  - number: do display but start at the given number

aio/src/app/custom-elements/contributor/contributor-list.component.spec.ts

@@ -63,7 +63,7 @@ describe('ContributorListComponent', () => {
   it('should set the query to the "GDE" group when user selects "GDE"', () => {
     component = getComponent();
     component.selectGroup('GDE');
-    expect(locationService.searchResult['group']).toBe('GDE');
+    expect(locationService.searchResult.group).toBe('GDE');
   });
 
   it('should set the query to the first group when user selects unknown name', () => {
@@ -71,7 +71,7 @@ describe('ContributorListComponent', () => {
     component.selectGroup('GDE'); // a legit group that isn't the first
 
     component.selectGroup('foo'); // not a legit group name
-    expect(locationService.searchResult['group']).toBe('Angular');
+    expect(locationService.searchResult.group).toBe('Angular');
   });
 
   //// Test Helpers ////

aio/src/app/custom-elements/contributor/contributor-list.component.ts

@@ -29,7 +29,7 @@ export class ContributorListComponent implements OnInit {
     private locationService: LocationService) { }
 
   ngOnInit() {
-    const groupName =  this.locationService.search()['group'] || '';
+    const groupName =  this.locationService.search().group || '';
     // no need to unsubscribe because `contributors` completes
     this.contributorService.contributors
       .subscribe(grps => {

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

@@ -40,6 +40,10 @@ export const ELEMENT_MODULE_LOAD_CALLBACKS_AS_ROUTES = [
   {
     selector: 'live-example',
     loadChildren: () => import('./live-example/live-example.module').then(m => m.LiveExampleModule)
+  },
+  {
+    selector: 'aio-events',
+    loadChildren: () => import('./events/events.module').then(m => m.EventsModule)
   }
 ];