Add offscreen clipboard cookbook example (GoogleChrome#797)

* Add offscreen clipboard cookbook example

* Clarify solution comment

* Apply suggestions from code review

* Update offscreen.js

@dotproto I took some time to consider, and I think keeping the messages and proper verifications in the workflow is a much better approach than simplifying to a purely instructive showing of the offscreen API. It not only demonstrates extension writing best-practice for completely new learners, but also gives the opportunity to demonstrate the potential for having multiple offscreen documents packaged into a project that could potentially be opened.

* Update cookbook/offscreen-clipboard-write/offscreen.html

* Apply suggestions from code review

* Add additional explanitory text

* Apply suggestions from code review

Co-authored-by: Joe Medley <[email protected]>

* Add a README

* Missing semi

* Rewrap at 80 char

This brings descriptive comments in line with the copyright header required by Google.

* Rewrap at 80 characters & clarify comments

* Remove unreachable return statement

Co-authored-by: IanStanion-google <[email protected]>
Co-authored-by: Joe Medley <[email protected]>

Author: 3 people

cookbook/offscreen-clipboard-write/README.md

@@ -0,0 +1,19 @@
+This recipe shows how to write a string to the system clipboard using the [Offscreen API][1].
+
+## Context
+
+As of January 2023, the web platform has to ways to interact with the clipboard: `document.execCommand()` and `navigator.clipboard` (see [MDN's docs][0]). Unfortunately, neither of these APIs are exposed to JavaScript workers. This means that in order for an extension to read from or write values to the system clipboard, the extension _must_ do so in a web page. Enter the Offscreen API. This API was introduced to give extension developers an unobtrusive way to use DOM APIs in the background.
+
+In the future, the Chrome team is planning to add clipboard support directly to extension service workers. As such, this recipe is written to make it as easy as possible to replace `addToClipboard()`'s offscreen document-based implementation with one that directly uses the appropriate clipboard API.
+
+## Running this extension
+
+1. Clone this repository.
+2. Load this directory in Chrome as an [unpacked extension][2].
+3. Open the Extension menu and click the extension named "Offscreen API - Clipboard".
+
+You will now have "Hello, World!" on your system clipboard.
+
+[0]: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard
+[1]: https://developer.chrome.com/docs/extensions/reference/offscreen/
+[2]: https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked

cookbook/offscreen-clipboard-write/background.js

@@ -0,0 +1,59 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// The value that will be written to the clipboard.
+const textToCopy = `Hello world!`;
+
+// When the browser action is clicked, `addToClipboard()` will use an offscreen
+// document to write the value of `textToCopy` to the system clipboard.
+chrome.action.onClicked.addListener(async () => {
+  await addToClipboard(textToCopy);
+});
+
+// Solution 1 - As of Jan 2023, service workers cannot directly interact with
+// the system clipboard using either `navigator.clipboard` or
+// `document.execCommand()`. To work around this, we'll create an offscreen
+// document and pass it the data we want to write to the clipboard.
+async function addToClipboard(value) {
+  // This pattern ensures that the offscreen document exists before we try to
+  // send it a message. If we didn't await the `hasDocument()` and
+  // `createDocument()` calls, the `sendMessage()` call could send a message
+  // before the offscreen document can register it's `runtime.onMessage`
+  // listener.
+  if (await chrome.offscreen.hasDocument()) {
+    console.debug('Offscreen doc already exists.');
+  } else {
+    console.debug('Creating a new offscreen document.');
+
+    await chrome.offscreen.createDocument({
+      url: 'offscreen.html',
+      reasons: [chrome.offscreen.Reason.CLIPBOARD],
+      justification: 'Write text to the clipboard.',
+    });
+  }
+
+  // Now that are sure we have an offscreen document, we can safely dispatch the
+  // message.
+  chrome.runtime.sendMessage({
+    type: 'copy-data-to-clipboard',
+    target: 'offscreen-doc',
+    data: value,
+  });
+}
+
+// Solution 2 – Once extension service workers can use the Clipboard API,
+// replace the offscreen document based implementation with something like this.
+async function addToClipboardV2(value) {
+  navigator.clipboard.writeText(value);
+}

cookbook/offscreen-clipboard-write/manifest.json

@@ -0,0 +1,13 @@
+{
+  "name": "Offscreen API - Clipboard",
+  "version": "1.0",
+  "manifest_version": 3,
+  "background": {
+    "service_worker": "background.js"
+  },
+  "action": {},
+  "permissions": [
+    "offscreen",
+    "clipboardWrite"
+  ]
+}

cookbook/offscreen-clipboard-write/offscreen.html

@@ -0,0 +1,3 @@
+<!DOCTYPE html>
+<textarea id="text"></textarea>
+<script src="offscreen.js""></script>

cookbook/offscreen-clipboard-write/offscreen.js

@@ -0,0 +1,68 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Once the message has been posted from the service worker, checks are made to
+// confirm the message type and target before proceeding. This is so that the
+// module can easily be adapted into existing workflows where secondary uses for
+// the document (or alternate offscreen documents) might be implemented.
+
+// Registering this listener when the script is first executed ensures that the
+// offscreen document will be able to receive messages when the promise returned
+// by `offscreen.createDocument()` resolves.
+chrome.runtime.onMessage.addListener(handleMessages);
+
+// This function performs basic filtering and error checking on messages before
+// dispatching the
+// message to a more specific message handler.
+async function handleMessages(message) {
+  // Return early if this message isn't meant for the offscreen document.
+  if (message.target !== 'offscreen-doc') {
+    return;
+  }
+
+  // Dispatch the message to an appropriate handler.
+  switch (message.type) {
+    case 'copy-data-to-clipboard':
+      handleClipboardWrite(message.data);
+      break;
+    default:
+      console.warn(`Unexpected message type received: '${message.type}'.`);
+  }
+}
+
+
+// We use a <textarea> element for two main reasons:
+//  1. preserve the formatting of multiline text,
+//  2. select the node's content using this element's `.select()` method.
+let textEl = document.querySelector('#text');
+
+// Use the offscreen document's `document` interface to write a new value to the
+// system clipboard.
+//
+// At the time this demo was created (Jan 2023) the `navigator.clipboard` API
+// requires that the window is focused, but offscreen documents cannot be
+// focused. As such, we have to fall back to `document.execCommand()`.
+async function handleClipboardWrite(data) {
+  // Error if we received the wrong kind of data.
+  if (typeof data !== 'string') {
+    throw new TypeError(`Value provided must be a 'string', got '${typeof data}'.`);
+  }
+
+  // `document.execCommand('copy')` works against the user's selection in a web
+  // page. As such, we must insert the string we want to copy to the web page
+  // and to select that content in the page before calling `execCommand()`.
+  textEl.value = data;
+  textEl.select();
+  document.execCommand('copy');
+}