feat: enhance native window.open to match the custom implementation's behavior (#19703)

Co-authored-by: Andy Locascio <andy@slack-corp.com>

docs/api/structures/post-body.md

@@ -0,0 +1,23 @@
+# PostBody Object
+
+* `data` Array<[PostData](./post-data.md)> - The post data to be sent to the
+  new window.
+* `contentType` String - The `content-type` header used for the data. One of
+  `application/x-www-form-urlencoded` or `multipart/form-data`. Corresponds to
+  the `enctype` attribute of the submitted HTML form.
+* `boundary` String (optional) - The boundary used to separate multiple parts of
+  the message. Only valid when `contentType` is `multipart/form-data`.
+
+Note that keys starting with `--` are not currently supported. For example, this will errantly submit as `multipart/form-data` when `nativeWindowOpen` is set to `false` in webPreferences:
+
+```html
+<form
+  target="_blank"
+  method="POST"
+  enctype="application/x-www-form-urlencoded"
+  action="https://postman-echo.com/post"
+>
+  <input type="text" name="--theKey">
+  <input type="submit">
+</form>
+```

docs/api/structures/post-data.md

@@ -0,0 +1,21 @@
+# PostData Object
+
+* `type` String - One of the following:
+  * `rawData` - The data is available as a `Buffer`, in the `rawData` field.
+  * `file` - The object represents a file. The `filePath`, `offset`, `length`
+    and `modificationTime` fields will be used to describe the file.
+  * `blob` - The object represents a `Blob`. The `blobUUID` field will be used
+    to describe the `Blob`.
+* `bytes` String (optional) - The raw bytes of the post data in a `Buffer`.
+  Required for the `rawData` type.
+* `filePath` String (optional) - The path of the file being uploaded. Required
+  for the `file` type.
+* `blobUUID` String (optional) - The `UUID` of the `Blob` being uploaded.
+  Required for the `blob` type.
+* `offset` Integer (optional) - The offset from the beginning of the file being
+  uploaded, in bytes. Only valid for `file` types.
+* `length` Integer (optional) - The length of the file being uploaded, in bytes.
+  If set to `-1`, the whole file will be uploaded. Only valid for `file` types.
+* `modificationTime` Double (optional) - The modification time of the file
+  represented by a double, which is the number of seconds since the `UNIX Epoch`
+  (Jan 1, 1970). Only valid for `file` types.

docs/api/web-contents.md

@@ -150,6 +150,10 @@ Returns:
 * `referrer` [Referrer](structures/referrer.md) - The referrer that will be
   passed to the new window. May or may not result in the `Referer` header being
   sent, depending on the referrer policy.
+* `postBody` [PostBody](structures/post-body.md) (optional) - The post data that
+  will be sent to the new window, along with the appropriate headers that will
+  be set. If no post data is to be sent, the value will be `null`. Only defined
+  when the window is being created by a form that set `target=_blank`.
 
 Emitted when the page requests to open a new window for a `url`. It could be
 requested by `window.open` or an external link like `<a target='_blank'>`.
@@ -162,7 +166,7 @@ new [`BrowserWindow`](browser-window.md). If you call `event.preventDefault()` a
 instance, failing to do so may result in unexpected behavior. For example:
 
 ```javascript
-myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options) => {
+myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {
   event.preventDefault()
   const win = new BrowserWindow({
     webContents: options.webContents, // use existing webContents if provided
@@ -170,7 +174,16 @@ myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition
   })
   win.once('ready-to-show', () => win.show())
   if (!options.webContents) {
-    win.loadURL(url) // existing webContents will be navigated automatically
+    const loadOptions = {
+      httpReferrer: referrer
+    }
+    if (postBody != null) {
+      const { data, contentType, boundary } = postBody
+      loadOptions.postData = postBody.data
+      loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`
+    }
+
+    win.loadURL(url, loadOptions) // existing webContents will be navigated automatically
   }
   event.newGuest = win
 })