Add CloseWatcher reference pages (#33910)

* Add CloseWatcher reference pages

* MDN linter

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* MDN linter 2

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* feedback

* Apply suggestions from code review

Co-authored-by: wbamberg <[email protected]>

* Apply suggestions from code review

Co-authored-by: wbamberg <[email protected]>

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: wbamberg <[email protected]>

files/en-us/web/api/closewatcher/cancel_event/index.md

@@ -0,0 +1,55 @@
+---
+title: "CloseWatcher: cancel event"
+short-title: cancel
+slug: Web/API/CloseWatcher/cancel_event
+page-type: web-api-event
+status:
+  - experimental
+browser-compat: api.CloseWatcher.cancel_event
+---
+
+{{APIRef("HTML DOM")}} {{SeeCompatTable}}
+
+A `cancel` event is fired at a {{domxref("CloseWatcher")}} object before the `close` event, so that `close` can be prevented from firing, if necessary. It is triggered by all close signals (e.g. the <kbd>Esc</kbd> key) as well as {{domxref("CloseWatcher.requestClose()")}}.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js-nolint
+addEventListener("cancel", (event) => { })
+
+oncancel = (event) => { }
+```
+
+## Event type
+
+An {{domxref("Event")}}.
+
+## Examples
+
+### Using the `cancel` event
+
+In this example, we ask the user to confirm that they really want to close the component, and if they don't, we cancel the event using {{domxref("Event.preventDefault()")}}, which prevents the `close` event from being fired.
+
+```js
+watcher.addEventListener("cancel", (e) => {
+  if (e.cancelable && hasUnsavedData) {
+    const userReallyWantsToClose = confirm("Are you sure you want to close?");
+    if (!userReallyWantsToClose) {
+      e.preventDefault();
+    }
+  }
+};
+
+// Trigger a close request manually
+watcher.requestClose();
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/closewatcher/close/index.md

@@ -0,0 +1,45 @@
+---
+title: "CloseWatcher: close() method"
+short-title: close()
+slug: Web/API/CloseWatcher/close
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.CloseWatcher.close
+---
+
+{{APIRef("HTML DOM")}} {{SeeCompatTable}}
+
+The **`close()`** method of the {{domxref("CloseWatcher")}} interface lets you skip any logic in the `cancel` event handler and immediately fire the `close` event. It then deactivates the close watcher as if `destroy()` was called.
+
+## Syntax
+
+```js-nolint
+close()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+None ({{jsxref("undefined")}}).
+
+## Examples
+
+### Using the `close()` method
+
+Use the `close()` method to deactivate the close watcher and destroy it.
+
+```js
+watcher.close();
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/closewatcher/close_event/index.md

@@ -0,0 +1,50 @@
+---
+title: "CloseWatcher: close event"
+short-title: close
+slug: Web/API/CloseWatcher/close_event
+page-type: web-api-event
+status:
+  - experimental
+browser-compat: api.CloseWatcher.close_event
+---
+
+{{APIRef("HTML DOM")}} {{SeeCompatTable}}
+
+A `close` event is fired at a {{domxref("CloseWatcher")}} object when a close request was received and only fired if the {{domxref("CloseWatcher.cancel_event", "cancel")}} event that preceded the `close` one was not canceled.
+
+The `close` event handler is where the code to close the UI component should be called: this ensures that the component will be closed properly either from the platform-specific close signal or from a call to {{domxref("CloseWatcher.requestClose()")}}.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js-nolint
+addEventListener("close", (event) => { })
+
+onclose = (event) => { }
+```
+
+## Event type
+
+An {{domxref("Event")}}.
+
+## Examples
+
+### Using the `close` event
+
+Use the `close` to listen for close requests.
+
+```js
+watcher.addEventListener("close", () => {
+  // Close your UI component
+  sidebar.hide();
+};
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/closewatcher/closewatcher/index.md

@@ -0,0 +1,58 @@
+---
+title: "CloseWatcher: CloseWatcher() constructor"
+short-title: CloseWatcher()
+slug: Web/API/CloseWatcher/CloseWatcher
+page-type: web-api-constructor
+status:
+  - experimental
+browser-compat: api.CloseWatcher.CloseWatcher
+---
+
+{{APIRef("HTML DOM")}} {{SeeCompatTable}}
+
+The **`CloseWatcher()`** constructor creates a new {{domxref("CloseWatcher")}} object.
+
+You can create `CloseWatcher` instances without [user activation](/en-US/docs/Web/Security/User_activation), and this can be useful to implement cases like session inactivity timeout dialogs. However, if you create more than one `CloseWatcher` without user activation, then the newly-created one will be grouped together with the last one, so a single close request will close them both. This means that it is important to call {{domxref("CloseWatcher.destroy()", "destroy()")}}, {{domxref("CloseWatcher.close()", "close()")}}, and {{domxref("CloseWatcher.requestClose()", "requestClose()")}} properly.
+
+## Syntax
+
+```js-nolint
+new CloseWatcher()
+new CloseWatcher(options)
+```
+
+### Parameters
+
+- `options` {{optional_inline}}
+  - : An object that has the following properties:
+    - `signal`
+      - : An {{domxref("AbortSignal")}}. If this is provided, then the watcher can be destroyed (as if by calling {{domxref("CloseWatcher.destroy()")}}) by calling {{domxref("AbortController.abort()")}} on the corresponding {{domxref("AbortController")}}.
+
+## Return value
+
+A new {{domxref("CloseWatcher")}} object.
+
+## Examples
+
+### Creating new `CloseWatcher` instances
+
+Create a new `CloseWatcher`.
+
+```js
+const watcher = new CloseWatcher();
+```
+
+Create a new `CloseWatcher` with an {{domxref("AbortSignal")}} that controls destroying the watcher.
+
+```js
+const controller = new AbortController();
+const signalWatcher = new CloseWatcher({ signal: controller.signal };
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/closewatcher/destroy/index.md

@@ -0,0 +1,47 @@
+---
+title: "CloseWatcher: destroy() method"
+short-title: destroy()
+slug: Web/API/CloseWatcher/destroy
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.CloseWatcher.destroy
+---
+
+{{APIRef("HTML DOM")}} {{SeeCompatTable}}
+
+The **`destroy()`** method of the {{domxref("CloseWatcher")}} interface deactivates the close watcher. This is intended to be called if the relevant UI element is torn down in some other way than being closed.
+
+After being deactivated, this `CloseWatcher` will no longer receive `cancel` or `close` events, and it will be possible to create new independent `CloseWatcher` instances.
+
+## Syntax
+
+```js-nolint
+destroy()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+None ({{jsxref("undefined")}}).
+
+## Examples
+
+### Using the `destroy()` method
+
+Use the `destroy()` method to dispose of the watcher instance for cleanup.
+
+```js
+watcher.destroy();
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/closewatcher/index.md

@@ -0,0 +1,78 @@
+---
+title: CloseWatcher
+slug: Web/API/CloseWatcher
+page-type: web-api-interface
+status:
+  - experimental
+browser-compat: api.CloseWatcher
+---
+
+{{APIRef("HTML DOM")}} {{SeeCompatTable}}
+
+The `CloseWatcher` interface listens and responds to close requests.
+
+Some UI components have "close behavior", meaning that the component appears, and the user can close it when they are finished with it. For example: sidebars, popups, dialogs, or notifications.
+
+Users generally expect to be able to use a particular mechanism to close these elements, and the mechanism tends to be device-specific. For example, on a device with a keyboard it might be the <kbd>Esc</kbd> key, but Android might use the back button. For built-in components, such as [popover](/en-US/docs/Web/API/Popover_API) or {{htmlelement("dialog")}} elements, the browser takes care of these differences, closing the element when the user performs the close action appropriate for the device. However, when a web developer implements their own closable UI component (for example, a sidebar), it is hard to implement this kind of device-specific close behavior. The `CloseWatcher` interface solves this problem by delivering a `close` event to the when the user executes the close action for the device.
+
+{{InheritanceDiagram}}
+
+The `CloseWatcher` interface inherits from {{domxref("EventTarget")}}.
+
+## Constructor
+
+- {{domxref("CloseWatcher.CloseWatcher", "CloseWatcher()")}} {{Experimental_Inline}}
+  - : Creates a new `CloseWatcher` instance.
+
+## Instance methods
+
+_This interface also inherits methods from its parent, {{domxref("EventTarget")}}._
+
+- {{domxref("CloseWatcher.requestClose()")}} {{Experimental_Inline}}
+  - : Fires a `cancel` event and if that event is not canceled with {{domxref("Event.preventDefault()")}}, proceeds to fire a `close` event, and then finally deactivates the close watcher as if `destroy()` was called.
+- {{domxref("CloseWatcher.close()")}} {{Experimental_Inline}}
+  - : Immediately fires the `close` event, without firing `cancel` first, and deactivates the close watcher as if `destroy()` was called.
+- {{domxref("CloseWatcher.destroy()")}} {{Experimental_Inline}}
+  - : Deactivates the close watcher so that it will no longer receive `close` events.
+
+## Events
+
+- {{domxref("CloseWatcher.cancel_event", "cancel")}} {{Experimental_Inline}}
+  - : An event fired before the `close` event, so that `close` can be prevented from firing.
+- {{domxref("CloseWatcher.close_event", "close")}} {{Experimental_Inline}}
+  - : An event fired when a close request was received.
+
+## Examples
+
+### Processing close requests
+
+In this example, you have your own UI component (a picker) and you want to support both, the platform's default close method (e.g. the <kbd>Esc</kbd> key) and your custom close method (a close button).
+
+You create a `CloseWatcher` to handle all `close` events.
+
+The `onclick` handler of your UI component can call `requestClose` to request a close and to route your close request through the same `onclose` handler the platform close method uses.
+
+```js
+const watcher = new CloseWatcher();
+const picker = setUpAndShowPickerDOMElement();
+let chosenValue = null;
+
+watcher.onclose = () => {
+  chosenValue = picker.querySelector("input").value;
+  picker.remove();
+};
+
+picker.querySelector(".close-button").onclick = () => watcher.requestClose();
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("HTMLDialogElement.close_event", "close")}} event on {{domxref("HTMLDialogElement")}}

files/en-us/web/api/closewatcher/requestclose/index.md

@@ -0,0 +1,56 @@
+---
+title: "CloseWatcher: requestClose() method"
+short-title: requestClose()
+slug: Web/API/CloseWatcher/requestClose
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.CloseWatcher.requestClose
+---
+
+{{APIRef("HTML DOM")}} {{SeeCompatTable}}
+
+The **`requestClose()`** method of the {{domxref("CloseWatcher")}} interface fires a `cancel` event and if that event is not canceled with {{domxref("Event.preventDefault()")}}, proceeds to fire a `close` event, and then finally deactivates the close watcher as if `destroy()` was called.
+
+## Syntax
+
+```js-nolint
+requestClose()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+None ({{jsxref("undefined")}}).
+
+## Examples
+
+### Using the `requestClose()` method
+
+In this example, you have your own UI component (a picker), and you want to support both the platform's default close method (e.g. the <kbd>Esc</kbd> key) and your custom close method (a close button).
+
+The `onclick` handler of your UI component can call `requestClose` to request a close and to route your close request through the same `onclose` handler the platform close method uses.
+
+```js
+const watcher = new CloseWatcher();
+const picker = setUpAndShowPickerDOMElement();
+let chosenValue = null;
+
+watcher.onclose = () => {
+  chosenValue = picker.querySelector("input").value;
+  picker.remove();
+};
+
+picker.querySelector(".close-button").onclick = () => watcher.requestClose();
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}