Editorial review: Document popover="hint"

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

@@ -12,6 +12,11 @@ The **`popoverTargetElement`** property of the {{domxref("HTMLButtonElement")}}
 
 It is the JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) HTML attribute.
 
+Establishing a relationship between a popover and its invoker button using the `popoverTargetElement` property has two additional useful effects:
+
+- The browser creates an implicit [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) and [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) relationship between popover and invoker, and places the popover in a logical position in the keyboard focus navigation order when shown. This makes the popover more accessible to keyboard and assistive technology (AT) users (see also [Popover accessibility features](/en-US/docs/Web/API/Popover_API/Using#popover_accessibility_features)).
+- The browser creates an implicit anchor reference between the two, making it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). See [Popover anchor positioning](/en-US/docs/Web/API/Popover_API/Using#popover_anchor_positioning) for more details.
+
 ## Value
 
 A reference to a popover element in the DOM.

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

@@ -13,8 +13,6 @@ browser-compat: api.HTMLElement.anchorElement
 
 The **`anchorElement`** property of the {{domxref("HTMLElement")}} interface returns a reference to the element's anchor element. This works only in the case of elements associated with their anchors via the [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) HTML attribute, not elements associated with their anchors via the CSS {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties.
 
-For detailed information on anchor features and usage, see the [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) module landing page and the [Using CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning/Using) guide.
-
 ## Value
 
 An {{domxref("HTMLElement")}} instance representing the element's anchor element, or `null` if it doesn't have one.
@@ -75,4 +73,3 @@ This attribute is not currently part of the HTML specification. Read the discuss
 - HTML [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute
 - CSS {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties
 - [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) module
-- [Using CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning/Using) guide

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

@@ -73,7 +73,7 @@ _Also inherits properties from its parent, {{DOMxRef("Element")}}._
     As a getter, it is the same as {{DOMxRef("HTMLElement.innerText")}} (it represents the rendered text content of an element and its descendants).
     As a setter, it replaces the selected node and its contents with the given value, converting any line breaks into {{HTMLElement("br")}} elements.
 - {{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.
+  - : Gets and sets an element's popover state via JavaScript (`"auto"`, `"hint"`, 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.spellcheck")}}
   - : A boolean value that controls the [spell-checking](/en-US/docs/Web/HTML/Global_attributes/spellcheck) hint. It is available on all HTML elements, though it doesn't affect all of them.
 - {{DOMxRef("HTMLElement.style")}}

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

@@ -8,20 +8,31 @@ browser-compat: api.HTMLElement.popover
 
 {{APIRef("Popover API")}}
 
-The **`popover`** property of the {{domxref("HTMLElement")}} interface gets and sets an element's popover state via JavaScript (`"auto"` or `"manual"`), and can be used for feature detection.
+The **`popover`** property of the {{domxref("HTMLElement")}} interface gets and sets an element's popover state via JavaScript (`"auto"`, `"hint"`, or `"manual"`), and can be used for feature detection.
 
 It reflects the value of the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) global HTML attribute.
 
 ## Value
 
 An enumerated value; possible values are:
 
-- `"auto"`: In [auto state](/en-US/docs/Web/API/Popover_API/Using#auto_state_and_light_dismiss):
-  - The popover can be "light dismissed" — this means that you can hide the popover by clicking outside it or pressing the <kbd>Esc</kbd> key.
-  - Usually, only one popover can be shown at a time — showing a second popover when one is already shown will hide the first one. The exception to this rule is when you have nested auto popovers. See [Nested popovers](/en-US/docs/Web/API/Popover_API/Using#nested_popovers) for more details.
-- `"manual"`: In [manual state](/en-US/docs/Web/API/Popover_API/Using#using_manual_popover_state):
-  - The popover cannot be "light dismissed", although declarative show/hide/toggle buttons will still work.
-  - Multiple independent popovers can be shown at a time.
+- `"auto"`
+
+  - : [`auto`](/en-US/docs/Web/API/Popover_API/Using#auto_state_and_light_dismiss) popovers can be "light dismissed" — this means that you can hide the popover by clicking outside it or pressing the <kbd>Esc</kbd> key.
+
+    Usually, only one `auto` popover can be shown at a time — showing a second popover when one is already shown will hide the first one. The exception to this rule is when you have nested auto popovers. See [Nested popovers](/en-US/docs/Web/API/Popover_API/Using#nested_popovers) for more details.
+
+- `"hint"`
+
+  - : [`hint`](/en-US/docs/Web/API/Popover_API/Using#using_hint_popover_state) popovers do not close `auto` popovers when they are displayed, but will close other hint popovers.
+    They can be light dismissed and will respond to close requests.
+
+    Usually they are shown and hidden in response to non-click JavaScript events such as [`mouseover`](/en-US/docs/Web/API/Element/mouseover_event)/[`mouseout`](/en-US/docs/Web/API/Element/mouseout_event) and [`focus`](/en-US/docs/Web/API/Element/focus_event)/[`blur`](/en-US/docs/Web/API/Element/blur_event).
+    Clicking a button to open a `hint` popover would cause an open `auto` popover to light-dismiss.
+
+- `"manual"`
+
+  - : [`manual`](/en-US/docs/Web/API/Popover_API/Using#using_manual_popover_state) popovers cannot be "light dismissed" are not automatically closed. Popovers must explicitly be displayed and closed using declarative show/hide/toggle buttons or JavaScript. Multiple independent `manual` popovers can be shown simultaneously.
 
 ## Examples
 

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

@@ -16,11 +16,21 @@ When `showPopover()` is called on an element with the [`popover`](/en-US/docs/We
 
 ```js-nolint
 showPopover()
+showPopover(options)
 ```
 
 ### Parameters
 
-None.
+- `options` {{optional_inline}}
+
+  - : An object that can contain the following properties:
+
+    - `source` {{optional_inline}}
+
+      - : An {{domxref("HTMLElement")}} reference; programmatically defines the invoker of the popover associated with the show action, that is, its control element. Establishing a relationship between a popover and its invoker using the `source` option has two useful effects:
+
+        - The browser places the popover in a logical position in the keyboard focus navigation order when shown. This makes the popover more accessible to keyboard users (see also [Popover accessibility features](/en-US/docs/Web/API/Popover_API/Using#popover_accessibility_features)).
+        - The browser creates an implicit anchor reference between the two, making it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). See [Popover anchor positioning](/en-US/docs/Web/API/Popover_API/Using#popover_anchor_positioning) for more details.
 
 ### Return value
 

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

@@ -21,15 +21,31 @@ When `togglePopover()` is called on an element with the [`popover`](/en-US/docs/
 ## Syntax
 
 ```js-nolint
+togglePopover()
 togglePopover(force)
+togglePopover(options)
 ```
 
 ### Parameters
 
-- `force`
+A boolean (`force`) or an options object:
+
+- `force` {{optional_inline}}
   - : A boolean, which causes `togglePopover()` to behave like {{domxref("HTMLElement.showPopover", "showPopover()")}} or {{domxref("HTMLElement.hidePopover", "hidePopover()")}}, except that it doesn't throw an exception if the popover is already in the target state.
     - If set to `true`, the popover is shown if it was initially hidden. If it was initially shown, nothing happens.
     - If set to `false`, the popover is hidden if it was initially shown. If it was initially hidden, nothing happens.
+- `options` {{optional_inline}}
+
+  - : An object that can contain the following properties:
+
+    - `force` {{optional_inline}}
+      - : A boolean; see the `force` description above.
+    - `source` {{optional_inline}}
+
+      - : An {{domxref("HTMLElement")}} reference; programmatically defines the invoker of the popover associated with the toggle action, that is, its control element. Establishing a relationship between a popover and its invoker using the `source` option has two useful effects:
+
+        - The browser places the popover in a logical position in the keyboard focus navigation order when shown. This makes the popover more accessible to keyboard users (see also [Popover accessibility features](/en-US/docs/Web/API/Popover_API/Using#popover_accessibility_features)).
+        - The browser creates an implicit anchor reference between the two, making it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). See [Popover anchor positioning](/en-US/docs/Web/API/Popover_API/Using#popover_anchor_positioning) for more details.
 
 ### Return value
 

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

@@ -12,6 +12,11 @@ The **`popoverTargetElement`** property of the {{domxref("HTMLInputElement")}} i
 
 It is the JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) HTML attribute.
 
+Establishing a relationship between a popover and its invoker button using the `popoverTargetElement` property has two additional useful effects:
+
+- The browser creates an implicit [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) and [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) relationship between popover and invoker, and places the popover in a logical position in the keyboard focus navigation order when shown. This makes the popover more accessible to keyboard and assistive technology (AT) users (see also [Popover accessibility features](/en-US/docs/Web/API/Popover_API/Using#popover_accessibility_features)).
+- The browser creates an implicit anchor reference between the two, making it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). See [Popover anchor positioning](/en-US/docs/Web/API/Popover_API/Using#popover_anchor_positioning) for more details.
+
 ## Value
 
 A reference to a popover element in the DOM.

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

@@ -41,7 +41,7 @@ See [Using the popover API](/en-US/docs/Web/API/Popover_API/Using) for a detaile
 ## HTML attributes
 
 - [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover)
-  - : A global attribute that turns an element into a popover element; takes a popover state (`"auto"` or `"manual"`) as its value.
+  - : A global attribute that turns an element into a popover element; takes a popover state (`"auto"`, `"hint"`, or `"manual"`) as its value.
 - [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget)
   - : Turns a {{htmlelement("button")}} or {{htmlelement("input")}} element into a popover control button; takes the ID of the popover element to control as its value.
 - [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction)
@@ -64,7 +64,7 @@ See [Using the popover API](/en-US/docs/Web/API/Popover_API/Using) for a detaile
 ### Instance properties
 
 - {{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.
+  - : Gets and sets an element's popover state via JavaScript (`"auto"`, `"hint"`, 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("HTMLButtonElement.popoverTargetElement")}} and {{domxref("HTMLInputElement.popoverTargetElement")}}
   - : Gets and sets the popover element being controlled by the control button. The JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) HTML attribute.
 - {{domxref("HTMLButtonElement.popoverTargetAction")}} and {{domxref("HTMLInputElement.popoverTargetAction")}}