docs(service-worker): improve `SwRegistrationOptions` docs and add example (#21842)

PR Close #21842

packages/examples/service-worker/registration-options/BUILD.bazel

@@ -0,0 +1,62 @@
+package(default_visibility = ["//visibility:public"])
+
+load("//packages/bazel:index.bzl", "protractor_web_test_suite")
+load("//tools:defaults.bzl", "ng_module", "ts_library")
+load("@npm_bazel_typescript//:index.bzl", "ts_devserver")
+
+ng_module(
+    name = "sw_registration_options_examples",
+    srcs = glob(
+        ["**/*.ts"],
+        exclude = ["**/*_spec.ts"],
+    ),
+    # TODO: FW-1004 Type checking is currently not complete.
+    type_check = False,
+    deps = [
+        "//packages/core",
+        "//packages/platform-browser",
+        "//packages/platform-browser-dynamic",
+        "//packages/service-worker",
+    ],
+)
+
+ts_library(
+    name = "sw_registration_options_e2e_tests_lib",
+    testonly = True,
+    srcs = glob(["**/e2e_test/*_spec.ts"]),
+    tsconfig = "//packages/examples:tsconfig-e2e.json",
+    deps = [
+        "//packages/examples/test-utils",
+        "//packages/private/testing",
+        "@npm//@types/jasminewd2",
+        "@npm//protractor",
+    ],
+)
+
+ts_devserver(
+    name = "devserver",
+    entry_module = "@angular/examples/service-worker/registration-options/main",
+    index_html = "//packages/examples:index.html",
+    port = 4200,
+    scripts = [
+        "//tools/rxjs:rxjs_umd_modules",
+        "@npm//node_modules/tslib:tslib.js",
+    ],
+    static_files = [
+        "ngsw-worker.js",
+        "@npm//node_modules/zone.js:dist/zone.js",
+    ],
+    deps = [":sw_registration_options_examples"],
+)
+
+protractor_web_test_suite(
+    name = "protractor_tests",
+    data = ["//packages/bazel/src/protractor/utils"],
+    on_prepare = "start-server.js",
+    server = ":devserver",
+    deps = [
+        ":sw_registration_options_e2e_tests_lib",
+        "@npm//protractor",
+        "@npm//selenium-webdriver",
+    ],
+)

packages/examples/service-worker/registration-options/e2e_test/registration-options_spec.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {browser, by, element} from 'protractor';
+import {verifyNoBrowserErrors} from '../../../test-utils';
+
+describe('SW `SwRegistrationOptions` example', () => {
+  const pageUrl = '/registration-options';
+  const appElem = element(by.css('example-app'));
+
+  afterEach(verifyNoBrowserErrors);
+
+  it('not register the SW by default', () => {
+    browser.get(pageUrl);
+    expect(appElem.getText()).toBe('SW enabled: false');
+  });
+
+  it('register the SW when navigating to `?sw=true`', () => {
+    browser.get(`${pageUrl}?sw=true`);
+    expect(appElem.getText()).toBe('SW enabled: true');
+  });
+});

packages/examples/service-worker/registration-options/main.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {platformBrowserDynamic} from '@angular/platform-browser-dynamic';
+import {AppModuleNgFactory} from './module.ngfactory';
+
+platformBrowserDynamic().bootstrapModuleFactory(AppModuleNgFactory);

packages/examples/service-worker/registration-options/module.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+// tslint:disable: no-duplicate-imports
+import {Component} from '@angular/core';
+// #docregion registration-options
+import {NgModule} from '@angular/core';
+import {BrowserModule} from '@angular/platform-browser';
+import {ServiceWorkerModule, SwRegistrationOptions} from '@angular/service-worker';
+// #enddocregion registration-options
+import {SwUpdate} from '@angular/service-worker';
+// tslint:enable: no-duplicate-imports
+
+@Component({
+  selector: 'example-app',
+  template: 'SW enabled: {{ swu.isEnabled }}',
+})
+export class AppComponent {
+  constructor(readonly swu: SwUpdate) {}
+}
+// #docregion registration-options
+
+@NgModule({
+  // #enddocregion registration-options
+  bootstrap: [
+    AppComponent,
+  ],
+  declarations: [
+    AppComponent,
+  ],
+  // #docregion registration-options
+  imports: [
+    BrowserModule,
+    ServiceWorkerModule.register('ngsw-worker.js'),
+  ],
+  providers: [
+    {
+      provide: SwRegistrationOptions,
+      useFactory: () => ({enabled: location.search.includes('sw=true')}),
+    },
+  ],
+})
+export class AppModule {
+}
+// #enddocregion registration-options

packages/examples/service-worker/registration-options/ngsw-worker.js

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+// Mock `ngsw-worker.js` used for testing the examples.
+// Immediately takes over and unregisters itself.
+self.addEventListener('install', evt => evt.waitUntil(self.skipWaiting()));
+self.addEventListener(
+    'activate',
+    evt => evt.waitUntil(self.clients.claim().then(() => self.registration.unregister())));

packages/examples/service-worker/registration-options/start-server.js

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+const protractorUtils = require('@angular/bazel/protractor-utils');
+const protractor = require('protractor');
+
+module.exports = async function(config) {
+  const {port} = await protractorUtils.runServer(config.workspace, config.server, '-port', []);
+  const serverUrl = `http://localhost:${port}`;
+
+  protractor.browser.baseUrl = serverUrl;
+};

packages/service-worker/src/module.ts

@@ -18,11 +18,29 @@ import {SwUpdate} from './update';
  * Token that can be used to provide options for `ServiceWorkerModule` outside of
  * `ServiceWorkerModule.register()`.
  *
+ * You can use this token to define a provider that generates the registration options at runtime,
+ * for example via a function call:
+ *
+ * {@example service-worker/registration-options/module.ts region="registration-options"
+ *     header="app.module.ts" linenums="false"}
+ *
  * @publicApi
  */
 export abstract class SwRegistrationOptions {
-  scope?: string;
+  /**
+   * Whether the ServiceWorker will be registered and the related services (such as `SwPush` and
+   * `SwUpdate`) will attempt to communicate and interact with it.
+   *
+   * Default: true
+   */
   enabled?: boolean;
+
+  /**
+   * A URL that defines the ServiceWorker's registration scope; that is, what range of URLs it can
+   * control. It will be used when calling
+   * [ServiceWorkerContainer#register()](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register).
+   */
+  scope?: string;
 }
 
 export const SCRIPT = new InjectionToken<string>('NGSW_REGISTER_SCRIPT');

packages/tsconfig.json

@@ -39,7 +39,7 @@
     "examples/**/e2e_test/*",
     // Exclude the "main.ts" files for each example group because this file is used by
     // Bazel to launch the devserver and uses AOT compilation.
-    "examples/*/main.ts",
+    "examples/**/main.ts",
     "platform-server/integrationtest",
     "router/test/aot_ngsummary_test",
   ]