Add popover documentation for methods, events, and psuedo selectors (#…

…26145) * add documentation on the popover attribute * add documentation on the popover events * add documentation on the popover methods * add documentation on the popover-open psuedo selector * Apply suggestions from code review --------- Co-authored-by: Michael[tm] Smith <[email protected]>
mdn · Apr 14, 2023 · 8448c8e · 8448c8e
1 parent 74e69c1
commit 8448c8e
Show file tree

Hide file tree

Showing 8 changed files with 388 additions and 0 deletions.
diff --git a/files/en-us/web/api/htmlelement/beforetoggle_event/index.md b/files/en-us/web/api/htmlelement/beforetoggle_event/index.md
@@ -0,0 +1,50 @@
+---
+title: "HTMLElement: beforetoggle event"
+slug: Web/API/HTMLElement/beforetoggle_event
+page-type: web-api-event
+browser-compat: api.HTMLElement.beforetoggle_event
+---
+
+{{APIRef}}
+
+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.
+
+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`.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener("beforetoggle", (event) => {});
+
+onbeforetoggle = (event) => {};
+```
+
+## Event type
+
+A {{domxref("ToggleEvent")}}. Inherits from {{domxref("Event")}}.
+
+{{InheritanceDiagram("ToggleEvent")}}
+
+## Event properties
+
+_This interface inherits properties from its parent {{DOMxRef("Event")}}._
+
+- {{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.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- Related event: [`toggle`](/en-US/docs/Web/API/HTMLElement/toggle_event)
+- The [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute
diff --git a/files/en-us/web/api/htmlelement/hidepopover/index.md b/files/en-us/web/api/htmlelement/hidepopover/index.md
@@ -0,0 +1,67 @@
+---
+title: "HTMLElement: hidePopover() method"
+short-title: hidePopover()
+slug: Web/API/HTMLElement/hidePopover
+page-type: web-api-instance-method
+browser-compat: api.HTMLElement.hidePopover
+---
+
+{{ APIRef("HTML DOM") }}
+
+The **`HTMLElement.hidePopover()`** method opens an element that has a valid [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute.
+
+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.
+
+## Syntax
+
+```js-nolint
+hidePopover()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+None ({{jsxref("undefined")}}).
+
+## Examples
+
+Open a popover when moving the mouse pointer over a button:
+
+### HTML
+
+```html
+<button onmouseover="myFunction()">Hover Menu</button>
+<div id="myPopover">Popover</div>
+```
+
+### JavaScript
+
+```js
+// On mouse-over, execute myFunction
+function myFunction() {
+  document.getElementById("myPopover").hidePopover();
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## 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")}}
diff --git a/files/en-us/web/api/htmlelement/showpopover/index.md b/files/en-us/web/api/htmlelement/showpopover/index.md
@@ -0,0 +1,48 @@
+---
+title: "HTMLElement: showPopover() method"
+short-title: showPopover()
+slug: Web/API/HTMLElement/showPopover
+page-type: web-api-instance-method
+browser-compat: api.HTMLElement.showPopover
+---
+
+{{ APIRef("HTML DOM") }}
+
+The **`HTMLElement.showPopover()`** method opens an element that has a valid [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute.
+
+When `showPopover()` is called on an element with the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute that is currently hidden, then a {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}} cancelable event will be fired followed by the popover opening and a {{domxref("HTMLElement/toggle_event", "toggle")}} event being fired.
+If the element is already open, then nothing will happen.
+
+## Syntax
+
+```js-nolint
+showPopover()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+None ({{jsxref("undefined")}}).
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- Related event handlers
+
+  - {{domxref("HTMLElement.beforetoggle_event", "HTMLElement.beforetoggle")}}
+  - {{domxref("HTMLElement.toggle_event", "HTMLElement.toggle")}}
+
+- Related methods
+
+  - {{domxref("HTMLElement.hidePopover", "HTMLElement.hidePopover")}}
+  - {{domxref("HTMLElement.togglePopover", "HTMLElement.togglePopover")}}
diff --git a/files/en-us/web/api/htmlelement/toggle_event/index.md b/files/en-us/web/api/htmlelement/toggle_event/index.md
@@ -0,0 +1,50 @@
+---
+title: "HTMLElement: toggle event"
+slug: Web/API/HTMLElement/toggle_event
+page-type: web-api-event
+browser-compat: api.HTMLElement.toggle_event
+---
+
+{{APIRef}}
+
+The **`toggle`** event fires when an element with the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute is about to be opened or closed.
+
+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`.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener("toggle", (event) => {});
+
+ontoggle = (event) => {};
+```
+
+## Event type
+
+A {{domxref("ToggleEvent")}}. Inherits from {{domxref("Event")}}.
+
+{{InheritanceDiagram("ToggleEvent")}}
+
+## Event properties
+
+_This interface inherits properties from its parent {{DOMxRef("Event")}}._
+
+- {{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.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- Related event: [`beforetoggle`](/en-US/docs/Web/API/HTMLElement/beforetoggle_event)
+- The [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute
diff --git a/files/en-us/web/api/htmlelement/togglepopover/index.md b/files/en-us/web/api/htmlelement/togglepopover/index.md
@@ -0,0 +1,49 @@
+---
+title: "HTMLElement: togglePopover() method"
+short-title: togglePopover()
+slug: Web/API/HTMLElement/togglePopover
+page-type: web-api-instance-method
+browser-compat: api.HTMLElement.togglePopover
+---
+
+{{ APIRef("HTML DOM") }}
+
+The **`HTMLElement.togglePopover()`** method opens an element that has a valid [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute.
+
+When `togglePopover()` is called on an element with the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute that is currently hidden, then a {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}} cancelable event will be fired, followed by the popover opening and a {{domxref("HTMLElement/toggle_event", "toggle")}} event being fired.
+
+If the element is already 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 being fired.
+
+## Syntax
+
+```js-nolint
+togglePopover()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+None ({{jsxref("undefined")}}).
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- Related event handlers
+
+  - {{domxref("HTMLElement.beforetoggle_event", "HTMLElement.beforetoggle")}}
+  - {{domxref("HTMLElement.toggle_event", "HTMLElement.toggle")}}
+
+- Related methods
+
+  - {{domxref("HTMLElement.hidePopover", "HTMLElement.hidePopover")}}
+  - {{domxref("HTMLElement.showPopover", "HTMLElement.showPopover")}}
diff --git a/files/en-us/web/api/toggleevent/index.md b/files/en-us/web/api/toggleevent/index.md
@@ -0,0 +1,40 @@
+---
+title: ToggleEvent
+slug: Web/API/ToggleEvent
+page-type: web-api-interface
+browser-compat: api.ToggleEvent
+---
+
+{{APIRef("UI Events")}}
+
+The **`ToggleEvent`** interface represents an event notifying the user of an element whose state toggles between being open or closed.
+
+{{InheritanceDiagram}}
+
+## Constructor
+
+- {{DOMxRef("ToggleEvent.ToggleEvent", "ToggleEvent()")}}
+  - : Creates an `ToggleEvent` object.
+
+## Instance properties
+
+_This interface inherits properties from its parents, {{DOMxRef("UIEvent")}} and {{DOMxRef("Event")}}._
+
+- {{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.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`beforetoggle` event](/en-US/docs/Web/API/HTMLElement/beforetoggle_event)
+- [`toggle` event](/en-US/docs/Web/API/HTMLElement/toggle_event)
+- The [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute
diff --git a/files/en-us/web/css/_colon_popover-open/index.md b/files/en-us/web/css/_colon_popover-open/index.md
@@ -0,0 +1,29 @@
+---
+title: ":popover-open"
+slug: Web/CSS/:popover-open
+page-type: css-pseudo-class
+browser-compat: css.selectors.popover-open
+---
+
+{{CSSRef}}
+
+The **`:popover-open`** [CSS](/en-US/docs/Web/CSS)
+[pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents an element with a
+[`popover` attribute](/en-US/docs/Web/HTML/Global_attributes/popover) that is in
+the open state.
+
+## Syntax
+
+```css
+:popover-open {
+  /* ... */
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
diff --git a/files/en-us/web/html/global_attributes/popover/index.md b/files/en-us/web/html/global_attributes/popover/index.md
@@ -0,0 +1,55 @@
+---
+title: popover
+slug: Web/HTML/Global_attributes/popover
+page-type: html-attribute
+browser-compat: html.global_attributes.popover
+---
+
+{{HTMLSidebar("Global_attributes")}}
+
+The **`popover`** [global attribute](/en-US/docs/Web/HTML/Global_attributes) is used to specify that the element should be hidden on the page until it is opened by interacting with an _invoking element_ (a `<button>` or `<input type="button">` with a [`popovertarget`](/en-US/docs/Web/HTML/button#popovertarget)), or manually via [`showPopover()`](/en-US/docs/Web/API/HTMLElement/showPopover/).
+
+## Usage notes
+
+- When open, the element will appear above all other elements on a separate top layer, and won't be influenced by parent elements {{cssxref('position')}} or {{cssxref('overflow')}} styling.
+
+- The {{cssxref(':popover-open')}} CSS pseudo-selector can be used to style the element when it is open.
+
+- The {{cssxref('::backdrop')}} CSS pseudo-element can be used to style the backdrop that is displayed behind the element; for example, to dim unreachable content behind the modal dialog.
+
+- {{HTMLElement('button')}} elements can open a popover by adding the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) attribute, with a value matching the [`id`](/en-US/docs/Web/HTML/Global_attributes#id) of the element with the `popover` attribute.
+
+- The {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}} and {{domxref("HTMLElement/toggle_event", "toggle")}} events can be used to determine when an element with `popover` will change from an open or closed state.
+
+## Examples
+
+## Simple example
+
+The following will render a button which will open a popover element.
+
+```html
+<button popovertarget="my-popover">Open Popover</button>
+
+<div popover id="my-popover">Greetings, one and all!</div>
+```
+
+{{EmbedLiveSample("Simple_example", "100%", 200)}}
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- The {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}} event
+- The {{domxref("HTMLElement/toggle_event", "toggle")}} event
+- {{domxref("HTMLElement/hidePopover", "element.hidePopover()")}}
+- {{domxref("HTMLElement/showPopover", "element.showPopover()")}}
+- {{domxref("HTMLElement/togglePopover", "element.togglePopover()")}}
+- The {{cssxref(":popover-open")}} pseudo-element
+- The {{cssxref("::backdrop")}} pseudo-element
+- [popover-polyfill](https://github.com/oddbird/popover-polyfill)