From 4cbd5ac28cf1d7d9588a1e90f5349815a5562d2a Mon Sep 17 00:00:00 2001
From: Brandon Payton <brandon@happycode.net>
Date: Wed, 14 Aug 2024 14:44:25 -0400
Subject: [PATCH] Ask users to report errors if Playground load fails (#1686)

## Motivation for the change, related issues

If Playground fails to load for a reason other than unsupported or
unapproved storage access, the error message does not tell the user
where they can report their issue.

This PR simply adds an "If the problem persists, please report an issue
on GitHub" line with a link to create a new Playground issue.

Fixes #1683

## Implementation details

This PR contains some code reorganization because the previous code
created a `<div>` and a `<button>` and reused them for various purposes.
There was an initial bit of element creation code that configured the
elements for the default case, and other cases overrode those defaults.
And in some cases we wanted to change the order of the button and/or add
messages.

That made it easy to break or get something wrong even though adding a
new message was such a small change.

So I just changed each branch to create its own elements instead of
reusing. Now the logic is separated like:
```js
if (e?.name === 'NotSupportedError') {
	document.body.append(await renderStorageErrorUI());
} else {
	document.body.append(renderGenericErrorUI(e));
}
```

## Testing

I tested manually by throwing errors in the various `try` blocks.
---
 packages/playground/remote/remote.html | 190 +++++++++++++++----------
 1 file changed, 114 insertions(+), 76 deletions(-)

diff --git a/packages/playground/remote/remote.html b/packages/playground/remote/remote.html
index de2b8077cb..eb61aea6af 100644
--- a/packages/playground/remote/remote.html
+++ b/packages/playground/remote/remote.html
@@ -23,6 +23,7 @@
 			}
 
 			body.has-error {
+				padding: 15px;
 				background: #f1f1f1;
 				display: flex;
 				flex-direction: column;
@@ -38,6 +39,7 @@
 			}
 			body.has-error button {
 				margin-top: 15px;
+				margin-bottom: 15px;
 				font-size: 20px;
 				padding: 5px 10px;
 				cursor: pointer;
@@ -86,101 +88,137 @@
 				document.body.className = 'has-error';
 				document.body.innerHTML = '';
 
+				if (e?.name === 'NotSupportedError') {
+					document.body.append(await renderStorageErrorUI());
+				} else {
+					document.body.append(renderGenericErrorUI(e));
+				}
+			} finally {
+				document.body.classList.remove('is-loading');
+			}
+
+			function renderGenericErrorUI(error) {
+				const fragment = document.createDocumentFragment();
+
 				const div = document.createElement('div');
 				div.className = 'error-message';
 				const userFriendlyMessage =
-					e?.userFriendlyMessage ||
+					error.userFriendlyMessage ||
 					'See the developer tools for error details.';
 				div.innerHTML =
 					'Ooops! WordPress Playground had a hiccup! <br/><br/> ' +
 					userFriendlyMessage;
-				document.body.append(div);
+				fragment.append(div);
 
 				const button = document.createElement('button');
 				button.innerText = 'Try again';
 				button.onclick = () => {
 					window.location.reload();
 				};
-				if (e?.name === 'NotSupportedError') {
-					/**
-					 * Chrome does not allow Service Workers to be registered from cross-origin iframes
-					 * when third-party cookies are disabled unless `requestStorageAccess()` is called
-					 * and the user grants storage access.
-					 *
-					 * Let's assess the situation and provide a helpful message.
-					 */
-					let hasStorageAccess = false;
-					try {
-						const { state } = await navigator.permissions.query({
-							name: 'storage-access',
-						});
-						hasStorageAccess = state === 'granted';
-					} catch (e) {
-						// noop
-					}
-
-					if (
-						hasStorageAccess ||
-						!('requestStorageAccess' in document)
-					) {
-						// The user has granted storage access, but the error still persists.
-						// Let's explain why.
-						div.innerText =
-							'It looks like you have disabled third-party cookies in your browser. This ' +
-							'also disables the Service Worker API used by WordPress Playground. Please re-enable ' +
-							'third-party cookies and try again.';
-					} else {
-						// The user has not granted storage access.
-						// There's a chance we can fix this by asking for storage access.
-						div.innerText =
-							'WordPress Playground needs to use storage in your browser';
-						button.innerText = 'Allow storage access';
-						button.onclick = async () => {
-							try {
-								await document.requestStorageAccess();
-								window.location.reload();
-							} catch (e) {
-								// Either the user denied storage access OR chrome is not allowing
-								// storage access to be requested from an iframe for some reason.
-
-								// The two errors are indistinguishable and just say "requestStorageAccess not allowed"
-								// https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/dom/document.cc;drc=daf56cfa413f10dee6aa15b0b1e4572fcf5578df;l=462
-								// It's confusing! But we can at least tell the user what to do.
-								div.innerHTML = `
-									<p>
-										Oops! Playground failed to start. Here's what to do:
-									</p>
-									
-									<h3>Did you disable third-party cookies?</h3>
-									<p>
-										It also disables the required Service Worker API. Please re-enable 
-										third-party cookies and try again.
-									</p>
-
-									<h3>Did you refuse to grant Playground storage access?</h3>
-									<p>
-										Click the button below and grant storage access. Note the button may 
-										not work if you have disabled third-party cookies in your browser.
-									</p>
-									`;
-								const reportIssues =
-									document.createElement('p');
-								reportIssues.innerHTML = `
-									If neither method helped, please 
+				fragment.append(button);
+
+				const reportIssues = document.createElement('p');
+				reportIssues.innerHTML = `
+					If the problem persists, please
+					<a href="https://github.com/WordPress/playground-tools/issues/new"
+						target="_blank"
+						>report an issue on GitHub</a>.
+				`;
+				fragment.append(reportIssues);
+
+				return fragment;
+			}
+
+			async function renderStorageErrorUI() {
+				const fragment = document.createDocumentFragment();
+
+				/**
+				 * Chrome does not allow Service Workers to be registered from cross-origin iframes
+				 * when third-party cookies are disabled unless `requestStorageAccess()` is called
+				 * and the user grants storage access.
+				 *
+				 * Let's assess the situation and provide a helpful message.
+				 */
+				let hasStorageAccess = false;
+				try {
+					const { state } = await navigator.permissions.query({
+						name: 'storage-access',
+					});
+					hasStorageAccess = state === 'granted';
+				} catch (e) {
+					// noop
+				}
+
+				if (hasStorageAccess || !('requestStorageAccess' in document)) {
+					const div = document.createElement('div');
+
+					// The user has granted storage access, but the error still persists.
+					// Let's explain why.
+					div.innerText =
+						'It looks like you have disabled third-party cookies in your browser. This ' +
+						'also disables the Service Worker API used by WordPress Playground. Please re-enable ' +
+						'third-party cookies and try again.';
+					fragment.append(div);
+
+					const button = document.createElement('button');
+					button.innerText = 'Try again';
+					button.onclick = () => {
+						window.location.reload();
+					};
+					fragment.append(button);
+				} else {
+					const div = document.createElement('div');
+
+					// The user has not granted storage access.
+					// There's a chance we can fix this by asking for storage access.
+					div.innerText =
+						'WordPress Playground needs to use storage in your browser.';
+					fragment.append(div);
+
+					const button = document.createElement('button');
+					button.innerText = 'Allow storage access';
+					fragment.append(button);
+
+					button.onclick = async () => {
+						try {
+							await document.requestStorageAccess();
+							window.location.reload();
+						} catch (e) {
+							// Either the user denied storage access OR chrome is not allowing
+							// storage access to be requested from an iframe for some reason.
+
+							// The two errors are indistinguishable and just say "requestStorageAccess not allowed"
+							// https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/dom/document.cc;drc=daf56cfa413f10dee6aa15b0b1e4572fcf5578df;l=462
+							// It's confusing! But we can at least tell the user what to do.
+							div.innerHTML = `
+								<p>
+									Oops! Playground failed to start. Here's what to do:
+								</p>
+
+								<h3>Did you disable third-party cookies?</h3>
+								<p>
+									It also disables the required Service Worker API. Please re-enable
+									third-party cookies and try again.
+								</p>
+
+								<h3>Did you refuse to grant Playground storage access?</h3>
+								<p>
+									Click the button below and grant storage access. Note the button may
+									not work if you have disabled third-party cookies in your browser.
+								</p>
+								<p>
+									If neither method helped, please
 									<a href="https://github.com/WordPress/playground-tools/issues/new"
-									   target="_blank">
+										target="_blank">
 										report an issue on GitHub
 									</a>.
+								</p>
 								`;
-								document.body.append(reportIssues);
-							}
-						};
-					}
+						}
+					};
 				}
 
-				document.body.append(button);
-			} finally {
-				document.body.classList.remove('is-loading');
+				return fragment;
 			}
 		</script>
 	</body>