Add new and update existing popover api docs

files/en-us/glossary/top_layer/index.md

@@ -0,0 +1,25 @@
+---
+title: Top layer
+slug: Glossary/Top_layer
+page-type: glossary-definition
+---
+
+The **top layer** is a specific layer in the [stacking context](/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context), which spans the entire width and height of the viewport and sits on top of all other layers displayed in a web document. It is created by the browser to contain elements that should appear on top of all other content on the page.
+
+Elements that will appear in the top layer include:
+
+- Fullscreen elements, i.e. elements that have been caused to display in fullscreen mode by a successful {{domxref("Element.requestFullscreen()")}} call.
+- {{htmlelement("dialog")}} elements displayed as a modal via a successful {{domxref("HTMLDialogElement.showModal()")}} call.
+- Popover elements shown via a successful {{domxref("HTMLElement.showPopover()")}} call.
+
+The following screenshot demonstrates how a shown popover element is placed in the top layer in Chrome:
+
+![An element in the top layer, as shown in the chrome devtools](top_layer_devtools.png)
+
+## See also
+
+- [The stacking context](/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context)
+- [The Fullscreen API](/en-US/docs/Web/API/Fullscreen_API)
+- [The Popover API](/en-US/docs/Web/API/Popover_API)
+- [Cascade layers](/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers#creating_layers)
+- {{cssxref("@layer")}}

files/en-us/web/api/element/requestfullscreen/index.md

@@ -19,6 +19,8 @@ it's now in full screen mode. If permission is denied, the promise is rejected a
 element receives a {{domxref("Element/fullscreenerror_event", "fullscreenerror")}} event instead. If the element has been
 detached from the original document, then the document receives these events instead.
 
+> **Note:** It is possible to put a {{domxref("Popover_API", "popover", "", "nocode")}} element (for example `<div popover>...</div>`) into fullscreen mode. However, if you try to call `requestFullscreen()` on a popover that is already being shown in the top layer (via {{domxref("HTMLElement.showPopover()")}}), the promise will reject, because the behavior doesn't make sense in that context.
+
 ## Syntax
 
 ```js-nolint
@@ -66,6 +68,7 @@ returned. The rejection handler receives one of the following exception values:_
     - The element is not permitted to use the `fullscreen` feature,
       either because of [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) configuration or other access control features.
     - The element and its document are the same node.
+    - The element is a popover that is already being shown via {{domxref("HTMLElement.showPopover()")}}.
 
 ## Security
 

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

@@ -40,6 +40,10 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._
   - : A {{domxref("HTMLMenuElement")}} representing the menu element to be displayed if the button is clicked and is of `type="menu"`.
 - {{domxref("HTMLButtonElement.name")}}
   - : A string representing the name of the object when submitted with a form. If specified, it must not be the empty string.
+- {{domxref("HTMLButtonElement.popoverTargetAction")}}
+  - : Gets and sets the action to be performed (`"hide"`, `"show"`, or `"toggle"`) on a popover element being controlled by a control button. It reflects the value of the [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) HTML attribute.
+- {{domxref("HTMLButtonElement.popoverTargetElement")}}
+  - : Gets and sets the popover element to control via a button. The JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) HTML attribute.
 - {{domxref("HTMLButtonElement.tabIndex")}}
   - : A `long` that represents this element's position in the tabbing order.
 - {{domxref("HTMLButtonElement.type")}}

files/en-us/web/api/htmlbuttonelement/popovertargetaction/index.md

@@ -0,0 +1,59 @@
+---
+title: "HTMLButtonElement: popoverTargetAction property"
+short-title: popoverTargetAction
+slug: Web/API/HTMLButtonElement/popoverTargetAction
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.HTMLButtonElement.popoverTargetAction
+---
+
+{{ APIRef("DOM") }}{{SeeCompatTable}}
+
+The **`popoverTargetAction`** property of the {{domxref("HTMLButtonElement")}} interface gets and sets the action to be performed (`"hide"`, `"show"`, or `"toggle"`) on a popover element being controlled by a control button.
+
+It reflects the value of the [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) HTML attribute.
+
+## Value
+
+An enumerated value. Possible values are:
+
+- `"hide"`
+  - : The button will hide a shown popover. If you try to hide an already hidden popover, no action will be taken.
+- `"show"`
+  - : The button will show a hidden popover. If you try to show an already showing popover, no action will be taken.
+- `"toggle"`
+  - : The button will toggle a popover between showing and hidden. If the popover is hidden, it will be shown; If the popover is showing, it will be hidden.
+
+## Examples
+
+```js
+function supportsPopover() {
+  return HTMLElement.prototype.hasOwnProperty("popover");
+}
+
+const popover = document.getElementById("mypopover");
+const toggleBtn = document.getElementById("toggleBtn");
+
+const popoverSupported = supportsPopover();
+
+if (popoverSupported) {
+  popover.popover = "auto";
+  toggleBtn.popoverTargetElement = popover;
+  toggleBtn.popoverTargetAction = "toggle";
+} else {
+  console.log("Popover API not supported.");
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Popover API](/en-US/docs/Web/API/Popover_API)

files/en-us/web/api/htmlbuttonelement/popovertargetelement/index.md

@@ -0,0 +1,52 @@
+---
+title: "HTMLButtonElement: popoverTargetElement property"
+short-title: popoverTargetElement
+slug: Web/API/HTMLButtonElement/popoverTargetElement
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.HTMLButtonElement.popoverTargetElement
+---
+
+{{ APIRef("DOM") }}{{SeeCompatTable}}
+
+The **`popoverTargetElement`** property of the {{domxref("HTMLButtonElement")}} interface gets and sets the popover element to control via a control button.
+
+It is the JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) HTML attribute.
+
+## Value
+
+A reference to a popover element in the DOM.
+
+## Examples
+
+```js
+function supportsPopover() {
+  return HTMLElement.prototype.hasOwnProperty("popover");
+}
+
+const popover = document.getElementById("mypopover");
+const toggleBtn = document.getElementById("toggleBtn");
+
+const popoverSupported = supportsPopover();
+
+if (popoverSupported) {
+  popover.popover = "auto";
+  toggleBtn.popoverTargetElement = popover;
+  toggleBtn.popoverTargetAction = "toggle";
+} else {
+  console.log("Popover API not supported.");
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Popover API](/en-US/docs/Web/API/Popover_API)

files/en-us/web/api/htmldialogelement/showmodal/index.md

@@ -10,10 +10,12 @@ browser-compat: api.HTMLDialogElement.showModal
 
 The **`showModal()`** method of the
 {{domxref("HTMLDialogElement")}} interface displays the dialog as a modal, over the top
-of any other dialogs that might be present. It displays into the top layer, along with a
+of any other dialogs that might be present. It displays in the {{glossary("top layer")}}, along with a
 {{cssxref('::backdrop')}} pseudo-element. Interaction outside the dialog is blocked and
 the content outside it is rendered inert.
 
+> **Note:** It is possible to create a {{htmlelement("dialog")}} element that is also a {{domxref("Popover_API", "popover", "", "nocode")}}, i.e. `<dialog popover>...</dialog>`. However, if you try to call `showModal()` on a popover that is already being shown in the top layer (via {{domxref("HTMLElement.showPopover()")}}), the call with fail, because the behavior doesn't make sense in that context.
+
 ## Syntax
 
 ```js-nolint
@@ -31,7 +33,7 @@ None ({{jsxref("undefined")}}).
 ### Exceptions
 
 - `InvalidStateError` {{domxref("DOMException")}}
-  - : Thrown if the dialog is already open (i.e. if the `open` attribute is already set on the {{htmlelement("dialog")}} element).
+  - : Thrown if the dialog is already open (i.e. if the `open` attribute is already set on the {{htmlelement("dialog")}} element), or if the dialog is also a popover that is already being shown.
 
 ## Examples
 

files/en-us/web/api/htmlelement/beforetoggle_event/index.md

@@ -9,9 +9,10 @@ browser-compat: api.HTMLElement.beforetoggle_event
 
 {{APIRef}}{{SeeCompatTable}}
 
-The **`beforetoggle`** event fires when an element with the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute is about to be opened or closed.
+The **`beforetoggle`** event of the {{domxref("HTMLElement")}} interface fires on a {{domxref("Popover_API", "popover", "", "nocode")}} element (i.e. one that has a valid [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute) just before it is shown or hidden.
 
-If the element is currently not open, then the `.oldState` property will be set to `closed` and the `.newState` property will be set to `open`; otherwise if the element is open, then `.oldState` will be `open` and `.newState` will be `closed`.
+- If the popover is currently hidden, the `event.oldState` property will be set to `closed` and the `event.newState` property will be set to `open`.
+- If the popover is currently showing, then `event.oldState` will be `open` and `event.newState` will be `closed`.
 
 ## Syntax
 
@@ -29,14 +30,21 @@ A {{domxref("ToggleEvent")}}. Inherits from {{domxref("Event")}}.
 
 {{InheritanceDiagram("ToggleEvent")}}
 
-## Event properties
+## Examples
 
-_This interface inherits properties from its parent {{DOMxRef("Event")}}._
+```js
+const popover = document.getElementById("mypopover");
+
+// ...
 
-- {{DOMxRef("ToggleEvent.oldState")}} {{ReadOnlyInline}}
-  - : Returns either `open` or `closed`, depending on which state the element is transitioning from.
-- {{DOMxRef("ToggleEvent.newState")}} {{ReadOnlyInline}}
-  - : Returns either `open` or `closed`, depending on which state the element is transitioning to.
+popover.addEventListener("beforetoggle", (event) => {
+  if (event.newState === "open") {
+    console.log("Popover is being shown");
+  } else {
+    console.log("Popover is being hidden");
+  }
+});
+```
 
 ## Specifications
 
@@ -48,5 +56,5 @@ _This interface inherits properties from its parent {{DOMxRef("Event")}}._
 
 ## See also
 
+- [Popover API](/en-US/docs/Web/API/Popover_API)
 - Related event: [`toggle`](/en-US/docs/Web/API/HTMLElement/toggle_event)
-- The [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute

files/en-us/web/api/htmlelement/hidepopover/index.md

@@ -10,9 +10,9 @@ browser-compat: api.HTMLElement.hidePopover
 
 {{ APIRef("HTML DOM") }}{{SeeCompatTable}}
 
-The **`HTMLElement.hidePopover()`** method opens an element that has a valid [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute.
+The **`hidePopover()`** method of the {{domxref("HTMLElement")}} interface hides a {{domxref("Popover_API", "popover", "", "nocode")}} element (i.e. one that has a valid [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute) by removing it from the {{glossary("top layer")}} and styling it with `display: none`.
 
-When `hidePopover()` is called on an element with the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute that is currently open, then a {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}} non-cancelable event will be fired, followed by the popover closing, and a {{domxref("HTMLElement/toggle_event", "toggle")}} event will be fired. If the element is already closed, then nothing will happen.
+When `hidePopover()` is called on an showing element with the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute, a {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}} event will be fired, followed by the popover being hidden, and then the {{domxref("HTMLElement/toggle_event", "toggle")}} event firing. If the element is already hidden, an error is thrown.
 
 ## Syntax
 
@@ -28,24 +28,48 @@ None.
 
 None ({{jsxref("undefined")}}).
 
+### Exceptions
+
+- `InvalidStateError` {{domxref("DOMException")}}
+  - : Thrown if the popover is already hidden.
+
 ## Examples
 
-Open a popover when moving the mouse pointer over a button:
+The following example provides functionality to toggle a popover on and off by pressing a particular key on the keyboard.
 
-### HTML
+First, some HTML:
 
 ```html
-<button onmouseover="myFunction()">Hover Menu</button>
-<div id="myPopover">Popover</div>
+<div id="mypopover">
+  <h2>Help!</h2>
+
+  <p>You can use the following commands to control the app</p>
+
+  <ul>
+    <li>Press <ins>C</ins> to order cheese</li>
+    <li>Press <ins>T</ins> to order tofu</li>
+    <li>Press <ins>B</ins> to order bacon</li>
+    <hr />
+    <li>Say "Service" to summon the robot waiter to take your order</li>
+    <li>Say "Escape" to engage the ejector seat</li>
+  </ul>
+</div>
 ```
 
-### JavaScript
+And now the JavaScript to wire up the functionality:
 
 ```js
-// On mouse-over, execute myFunction
-function myFunction() {
-  document.getElementById("myPopover").hidePopover();
-}
+const popover = document.getElementById("mypopover");
+
+document.addEventListener("keydown", (event) => {
+  if (event.key === "h") {
+    if (popover.matches(":popover-open")) {
+      popover.hidePopover();
+    } else {
+      popover.showPopover();
+    }
+  }
+});
 ```
 
 ## Specifications
@@ -58,12 +82,4 @@ function myFunction() {
 
 ## See also
 
-- Related event handlers
-
-  - {{domxref("HTMLElement.beforetoggle_event", "HTMLElement.beforetoggle")}}
-  - {{domxref("HTMLElement.toggle_event", "HTMLElement.toggle")}}
-
-- Related methods
-
-  - {{domxref("HTMLElement.showPopover", "HTMLElement.showPopover")}}
-  - {{domxref("HTMLElement.togglePopover", "HTMLElement.togglePopover")}}
+- [Popover API](/en-US/docs/Web/API/Popover_API)

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

@@ -43,8 +43,8 @@ _Inherits properties from its parent, {{DOMxRef("Element")}}._
     As a setter, it replaces the content inside the selected element, converting any line breaks into {{HTMLElement("br")}} elements.
 - {{DOMxRef("HTMLElement.inputMode")}}
   - : A string value reflecting the value of the element's [`inputmode`](/en-US/docs/Web/HTML/Global_attributes/inputmode) attribute.
-- {{DOMxRef("HTMLElement.popover")}} {{Experimental_Inline}}
-  - : A string value reflecting the value of the element's [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute.
+- {{domxref("HTMLElement.popover")}}
+  - : Gets and sets an element's popover state via JavaScript (`"auto"` or `"manual"`), and can be used for feature detection. Reflects the value of the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) global HTML attribute.
 - {{DOMxRef("HTMLElement.lang")}}
   - : A string representing the language of an element's attributes, text, and element contents.
 - {{DOMxRef("HTMLElement.noModule")}}
@@ -91,11 +91,11 @@ _Inherits methods from its parent, {{DOMxRef("Element")}}._
 - {{DOMxRef("HTMLElement.focus()")}}
   - : Makes the element the current keyboard focus.
 - {{DOMxRef("HTMLElement.hidePopover()")}} {{Experimental_Inline}}
-  - : Hides the element, if it has a valid {{DOMxRef("HTMLElement.popover")}} value.
+  - : Hides a popover element by removing it from the {{glossary("top layer")}} and styling it with `display: none`.
 - {{DOMxRef("HTMLElement.showPopover()")}} {{Experimental_Inline}}
-  - : Shows the element, promoting it to the top layer, if it has a valid {{DOMxRef("HTMLElement.popover")}} value.
+  - : Shows a popover element by adding it to the {{glossary("top layer")}} and removing `display: none;` from its styles.
 - {{DOMxRef("HTMLElement.togglePopover()")}} {{Experimental_Inline}}
-  - : Hides or shows the element, if it has a valid {{DOMxRef("HTMLElement.popover")}} value.
+  - : Toggles a popover element between the hidden and showing states.
 
 ## Events