[Feature Request]: Document webcontents.on('close')

[mesner]

Preflight Checklist

• I have read the Contributing Guidelines for this project.
• I agree to follow the Code of Conduct that this project adheres to.
• I have searched the issue tracker for a feature request that matches the one I want to file, without success.

Problem Description

• Render processes that execute 'window.close()' within a BrowserView do not result in the window closing (see fiddle gist here, executed on v21.2.2: https://gist.github.com/mesner/56cdab123bd4cdd890641303b0d29afe).
• I've not found any documented way of determining if a window in a browserview has programmatically called close
• I've instead found an undocumented / private 'close' event on webcontents here: https://github.com/electron/electron/blob/main/shell/browser/api/electron_api_web_contents.cc#L1215
• The gist shows that the event is fired by logging "WEBCONTENTS.CLOSE" within the browserview
• The webcontents close method is being added in v22 here: feat: add webContents.close() #35509
• Note that the gist does not display a BrowserView in v22.beta.3. I have not diagnosed why.

Proposed Solution

• If approved, I believe the only necessary changes are to add the event to docs/api/web-contents.md and listeners and ensure they are fired in spec/api-web-contents-spec.ts.
• EDIT: I see that a preventDefault is added by default to emitted events. Should the CloseContents() method return early if it is prevented?

Alternatives Considered

• Have window.close() within a browserview close the browserwindow it belongs to? This seems to have more risk of impact.
• EDIT: browserview.on('close') event, but that would be the first documented BV event

Additional Information

I'd be happy to submit a PR for this if approved.

[codebytere]

@nornagon what do you think?

[tdozbun-reno]

I see that a preventDefault is added by default to emitted events. Should the CloseContents() method return early if it is prevented?

This would be really nice to have, I'm currently dealing with a website that can call window.close(), which destroys the browser view and is not cancellable (the window stays open). my current choices are between recreating the view (and re-attaching events), or replacing window.close in the client JS with a stub.