Mount a directory from the browser (#1482)

bgrgicak · web-flow · commit 09c2d17831e5 · 2024-06-02T21:47:52.000+02:00
## Motivation for the change, related issues

We would like to enable developers to mount local directories into their
Playground-based projects by prompting users to select a directory.
After the directory is selected the folder can be mounted into
Playground and used by it.

For example, this could be used to load local plugins and themes into
Playground.

## Implementation details

This PR adds a window message listener that takes the provided directory
handle and mounts it to the mountpoint.

```javascript
window.showDirectoryPicker().then(function (directoryHandle) {
	window.parent.postMessage({
		type: 'mount-directory-handle',
		directoryHandle,
		mountpoint: '/wordpress/wp-content/uploads/markdown/',
	});
});
```

## Testing Instructions (or ideally a Blueprint)

- Add this code after line 280 in
`packages/playground/remote/src/lib/worker-thread.ts`
```


	primaryPhp.writeFile(
		'/wordpress/mount.php',
		`&lt;!DOCTYPE html&gt;
		&lt;html&gt;
		&lt;head&gt;
			&lt;title&gt;Directory picker&lt;/title&gt;
		&lt;/head&gt;
		&lt;body&gt;
			&lt;button id="pick"&gt;Pick directory&lt;/button&gt;
			&lt;script&gt;
				document.getElementById('pick').addEventListener('click', function() {
					if (!('showDirectoryPicker' in window)) {
						alert('Your browser does not support the Directory Picker API');
						return;
					}
					window.showDirectoryPicker().then(function(directoryHandle) {
						window.parent.postMessage(
							{
								type: 'mount-directory-handle',
								directoryHandle,
								mountpoint: '/wordpress/wp-content/uploads/markdown/',
							}
						);
					});
				});
			&lt;/script&gt;
		&lt;/body&gt;
		&lt;/html&gt;`
	);
```

- open this blueprint
http://localhost:5400/website-server/?url=/mount.php
- Click the button and select a local folder that contains an HTML file
- Change the URL in the Playground header to
`/wp-content/uploads/markdown/YOUR-HTML-FILE.html`
- Confirm that your file was loaded
diff --git a/packages/docs/site/docs/10-javascript-api/06-mount-data.md b/packages/docs/site/docs/10-javascript-api/06-mount-data.md
@@ -0,0 +1,15 @@
+# Mount data
+
+## Mount a directory from the browser
+
+You can mount a directory from the browser to Playground using the `window.showDirectoryPicker` API. Check the [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/API/Window/showDirectoryPicker#browser_compatibility) before using this API.
+
+```javascript
+window.showDirectoryPicker().then(function (directoryHandle) {
+	window.parent.postMessage({
+		type: 'mount-directory-handle',
+		directoryHandle,
+		mountpoint: '/wordpress/wp-content/uploads/markdown/',
+	});
+});
+```
diff --git a/packages/playground/remote/src/lib/boot-playground-remote.ts b/packages/playground/remote/src/lib/boot-playground-remote.ts
@@ -9,7 +9,7 @@ import {
 	exposeAPI,
 	consumeAPI,
 	setupPostMessageRelay,
-	SyncProgressCallback
+	SyncProgressCallback,
 } from '@php-wasm/web';
 
 import type { PlaygroundWorkerEndpoint } from './worker-thread';
@@ -221,6 +221,7 @@ export async function bootPlaygroundRemote() {
 			wpFrame,
 			getOrigin((await playground.absoluteUrl)!)
 		);
+		setupMountListener(playground);
 		if (withNetworking) {
 			await setupFetchNetworkTransport(workerApi);
 		}
@@ -242,6 +243,27 @@ function getOrigin(url: string) {
 	return new URL(url, 'https://example.com').origin;
 }
 
+function setupMountListener(playground: WebClientMixin) {
+	window.addEventListener('message', async (event) => {
+		if (typeof event.data !== 'object') {
+			return;
+		}
+		if (event.data.type !== 'mount-directory-handle') {
+			return;
+		}
+		if (typeof event.data.directoryHandle !== 'object') {
+			return;
+		}
+		if (!event.data.mountpoint) {
+			return;
+		}
+		await playground.bindOpfs({
+			opfs: event.data.directoryHandle,
+			mountpoint: event.data.mountpoint,
+		});
+	});
+}
+
 function parseVersion<T>(value: string | undefined | null, latest: T) {
 	if (!value || value === 'latest') {
 		return latest as string;
