feat(service-worker): add openWindow, focusLastFocusedOrOpen and navigateLastFocusedOrOpen (angular#42520)

Add `openWindow`, `focusLastFocusedOrOpen` and `navigateLastFocusedOrOpen` abilty to the notificationclick handler such that when either a notification or notification action is clicked the service-worker can act accordinly without the need for the app to be open

PR Close angular#26907

PR Close angular#42520

Author: codingnuclei

.pullapprove.yml

@@ -617,6 +617,7 @@ groups:
           'aio/content/guide/service-worker-config.md',
           'aio/content/guide/service-worker-devops.md',
           'aio/content/guide/service-worker-intro.md',
+          'aio/content/guide/service-worker-notifications.md',
           'aio/content/images/guide/service-worker/**'
           ])
     reviewers:

aio/content/guide/service-worker-communications.md

@@ -95,4 +95,4 @@ You can subscribe to `SwUpdate#unrecoverable` to be notified and handle these er
 ## More on Angular service workers
 
 You may also be interested in the following:
-* [Service Worker in Production](guide/service-worker-devops).
+* [Service Worker Notifications](guide/service-worker-notifications).

aio/content/guide/service-worker-intro.md

@@ -66,6 +66,7 @@ The rest of the articles in this section specifically address the Angular implem
 
 * [App Shell](guide/app-shell)
 * [Service Worker Communication](guide/service-worker-communications)
+* [Service Worker Notifications](guide/service-worker-notifications)
 * [Service Worker in Production](guide/service-worker-devops)
 * [Service Worker Configuration](guide/service-worker-config)
 

aio/content/guide/service-worker-notifications.md

@@ -0,0 +1,106 @@
+# Service worker notifications
+
+Push notifications are a compelling way to engage users. Through the power of service workers, notifications can be delivered to a device even when your application is not in focus.
+
+The Angular service worker enables the display of push notifications and the handling of notification click events.
+
+<div class="alert is-helpful">
+
+  When using the Angular service worker, push notification interactions are handled using the `SwPush` service.
+  To learn more about the native APIs involved see [Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) and [Using the Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API).
+
+</div>
+
+#### Prerequisites
+
+We recommend you have a basic understanding of the following:
+
+- [Getting Started with Service Workers](guide/service-worker-getting-started).
+
+## Notification payload
+
+Invoke push notifications by pushing a message with a valid payload. See `SwPush` for guidance.
+
+<div class="alert is-helpful">
+
+  In Chrome, you can test push notifications without a backend.
+  Open Devtools -> Application -> Service Workers and use the `Push` input to send a JSON notification payload.
+
+</div>
+
+## Notification click handling
+
+The default behavior for the `notificationclick` event is to close the notification and notify `SwPush.notificationClicks`.
+
+You can specify an additional operation to be executed on `notificationclick` by adding an `onActionClick` property to the `data` object, and providing a `default` entry. This is especially useful for when there are no open clients when a notification is clicked.
+
+```json
+{
+  "notification": {
+    "title": "New Notification!",
+    "data": {
+      "onActionClick": {
+        "default": {"operation": "openWindow", "url": "foo"}
+      }
+    }
+  }
+}
+```
+
+### Operations
+
+The Angular service worker supports the following operations:
+
+- `openWindow`: Opens a new tab at the specified URL, which is resolved relative to the service worker scope.
+
+- `focusLastFocusedOrOpen`: Focuses the last focused client. If there is no client open, then it opens a new tab at the specified URL, which is resolved relative to the service worker scope.
+
+- `navigateLastFocusedOrOpen`: Focuses the last focused client and navigates it to the specified URL, which is resolved relative to the service worker scope. If there is no client open, then it opens a new tab at the specified URL.
+
+<div class="alert is-important">
+
+  If an `onActionClick` item does not define a `url`, then the service worker's registration scope is used.
+  
+</div>
+
+### Actions
+
+Actions offer a way to customize how the user can interact with a notification.
+
+Using the `actions` property, you can define a set of available actions. Each action is represented as an action button that the user can click to interact with the notification.
+
+In addition, using the `onActionClick` property on the `data` object, you can tie each action to an operation to be performed when the corresponding action button is clicked:
+
+```ts
+{
+  "notification": {
+    "title": "New Notification!",
+    "actions": [
+      {"action": "foo", "title": "Open new tab"},
+      {"action": "bar", "title": "Focus last"},
+      {"action": "baz", "title": "Navigate last"},
+      {"action": "qux", "title": "Just notify existing clients"}
+    ],
+    "data": {
+      "onActionClick": {
+        "default": {"operation": "openWindow"},
+        "foo": {"operation": "openWindow", "url": "/absolute/path"},
+        "bar": {"operation": "focusLastFocusedOrOpen", "url": "relative/path"},
+        "baz": {"operation": "navigateLastFocusedOrOpen", "url": "https://other.domain.com/"}
+      }
+    }
+  }
+}
+```
+
+<div class="alert is-important">
+
+  If an action does not have a corresponding `onActionClick` entry, then the notification is closed and `SwPush.notificationClicks` is notified on existing clients.
+
+</div>
+
+## More on Angular service workers
+
+You may also be interested in the following:
+
+- [Service Worker in Production](guide/service-worker-devops).

aio/content/navigation.json

@@ -435,6 +435,11 @@
               "title": "Service Worker Communication",
               "tooltip": "Services that enable you to interact with an Angular service worker."
             },
+            {
+              "url": "guide/service-worker-notifications",
+              "title": "Service Worker Notifications",
+              "tooltip": "Configuring service worker notification behavior."
+            },
             {
               "url": "guide/service-worker-devops",
               "title": "Service Worker in Production",

packages/service-worker/src/push.ts

@@ -81,6 +81,9 @@ import {ERR_SW_NOT_SUPPORTED, NgswCommChannel, PushEvent} from './low_level';
  * <code-example path="service-worker/push/module.ts" region="subscribe-to-notification-clicks"
  * header="app.component.ts"></code-example>
  *
+ * You can read more on handling notification clicks in the [Service worker notifications
+ * guide](guide/service-worker-notifications).
+ *
  * @see [Push Notifications](https://developers.google.com/web/fundamentals/codelabs/push-notifications/)
  * @see [Angular Push Notifications](https://blog.angular-university.io/angular-push-notifications/)
  * @see [MDN: Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)

packages/service-worker/worker/src/driver.ts

@@ -348,12 +348,52 @@ export class Driver implements Debuggable, UpdateSource {
     NOTIFICATION_OPTION_NAMES.filter(name => name in notification)
         .forEach(name => options[name] = notification[name]);
 
+    const notificationAction = action === '' || action === undefined ? 'default' : action;
+
+    const onActionClick = notification?.data?.onActionClick[notificationAction];
+
+    const urlToOpen = new URL(onActionClick?.url ?? '', this.scope.registration.scope).href;
+
+    switch (onActionClick?.operation) {
+      case 'openWindow':
+        await this.scope.clients.openWindow(urlToOpen);
+        break;
+      case 'focusLastFocusedOrOpen': {
+        let matchingClient = await this.getLastFocusedMatchingClient(this.scope);
+        if (matchingClient) {
+          await matchingClient?.focus();
+        } else {
+          await this.scope.clients.openWindow(urlToOpen);
+        }
+        break;
+      }
+      case 'navigateLastFocusedOrOpen': {
+        let matchingClient = await this.getLastFocusedMatchingClient(this.scope);
+        if (matchingClient) {
+          matchingClient = await matchingClient.navigate(urlToOpen);
+          await matchingClient?.focus();
+        } else {
+          await this.scope.clients.openWindow(urlToOpen);
+        }
+        break;
+      }
+      default:
+        break;
+    }
+
     await this.broadcast({
       type: 'NOTIFICATION_CLICK',
       data: {action, notification: options},
     });
   }
 
+  private async getLastFocusedMatchingClient(scope: ServiceWorkerGlobalScope):
+      Promise<WindowClient|null> {
+    const windowClients = await scope.clients.matchAll({type: 'window'});
+
+    // As per the spec windowClients are `sorted in the most recently focused order`
+    return windowClients[0];
+  }
   private async reportStatus(client: Client, promise: Promise<void>, nonce: number): Promise<void> {
     const response = {type: 'STATUS', nonce, status: true};
     try {

packages/service-worker/worker/src/service-worker.d.ts

@@ -36,21 +36,25 @@ declare class Client {
 }
 
 interface Clients {
-  claim(): Promise<any>;
+  claim(): Promise<void>;
   get(id: string): Promise<Client>;
-  matchAll(options?: ClientMatchOptions): Promise<Array<Client>>;
+  matchAll<T extends ClientMatchOptions>(
+    options?: T
+  ): Promise<ReadonlyArray<T['type'] extends 'window' ? WindowClient : Client>>;
+  openWindow(url: string): Promise<WindowClient | null>;
 }
 
 interface ClientMatchOptions {
   includeUncontrolled?: boolean;
   type?: ClientMatchTypes;
 }
 
-interface WindowClient {
-  focused: boolean;
-  visibilityState: WindowClientState;
+interface WindowClient extends Client {
+  readonly ancestorOrigins: ReadonlyArray<string>;
+  readonly focused: boolean;
+  readonly visibilityState: VisibilityState;
   focus(): Promise<WindowClient>;
-  navigate(url: string): Promise<WindowClient>;
+  navigate(url: string): Promise<WindowClient | null>;
 }
 
 type ClientFrameType = 'auxiliary'|'top-level'|'nested'|'none';