docs: clipboard.getNativeFormat() and clipboard.writeBuffers()

[coreh]

Hey folks 👋

Here's an initial version of the specs for the proposed clipboard.getNativeFormat() and clipboard.writeBuffers() API methods that we started working on during the contributor training

cc @itsananderson @loc

[nornagon]

Presumably the only useful application of this value would be to pass it into the new clipboard.writeBuffers (or existing clipboard.writeBuffer) function, yes?

So this would be used like:

clipboard.writeBuffers({
  [clipboard.getNativeFormat('text')]: Buffer.from(...),
  [myCustomFormat[os.platform()]]: Buffer.from(...),
})

That seems a little awkward to me, though I'm not sure I have a better suggestion. Here are some random thoughts, maybe useful, maybe not.

1. Given that custom formats will also necessarily be platform-specific, how do we expect users of the API to handle those? Should we have some examples to guide best practices?
2. These values are effectively constants. Should we expose them as such? e.g. clipboard.format.TEXT
3. Could we use JS Symbols effectively here...? e.g. if clipboard.format.TEXT was a special symbol, that could distinguish it from custom formats while avoiding the collision problem.

[jkleinsc]

Chromium is implementing raw clipboard access which should accomplish the same goal as this API.
Details here: https://bugs.chromium.org/p/chromium/issues/detail?id=897289. I've tested this functionality in Electron and what has been implemented in Chromium is available in Electron in the renderer (raw write is implemented; raw read is in process and not yet available). If we need this functionality in the main process we should use the same api shapes used by Chromium.

The explainer here has a pretty good summary of the API:
https://github.com/WICG/raw-clipboard-access/blob/master/explainer.md

[itsananderson]

I wrote up a really basic Fiddle for testing the Chromium feature, in case it's a helpful jumpstart for anyone: https://gist.github.com/2802c6a3744a31d3a81961bc118632d2 - I didn't do anything fancy to write custom binary formats, but it should be simple to add.

Exposing a compatible API in the main process does seem useful, especially since renderer processes are restricted to reading/writing the clipboard when they have user focus. We may need to make small adjustments to the API, like swapping Buffers for Blobs for binary clipboard values.

[henrit]

Chromium's raw clipboard API was abandoned last June. Its implementation has been scrubbed from the chromium codebase.

There is now instead a proposal for standardizing Pickling for Async Clipboard API, but it is explicitly designed to prevent setting arbitrary formats on the clipboard in the ways a native app would.

This leaves Electron users in the position of continuing to put together one-off node.js native clipboard modules, or waiting for this proposed change to land.