Editorial review: Document popover="hint"

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

@@ -12,6 +12,8 @@ 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.
 
+Associating a popover with a control using the `popoverTargetElement` property creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties.
+
 ## Value
 
 A reference to a popover element in the DOM.

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,29 @@ 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"`
+
+  - : In [auto state](/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 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 are similar to `auto` popovers, but with a significant difference. They can be light-dismissed, but they do not light-dismiss `auto` popovers when shown, only `hint` popovers. `hint` popovers tend to be 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). When clicking on a button, the click itself would cause an open `auto` popover to light-dismiss.
+
+- `"manual"`
+
+  - : In [manual state](/en-US/docs/Web/API/Popover_API/Using#using_manual_popover_state):
+    - Popovers cannot be "light dismissed", although declarative show/hide/toggle buttons will still work.
+    - Multiple independent popovers can be shown at a time.
 
 ## Examples
 

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

@@ -16,11 +16,17 @@ 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 toggle action, that is, the control button or link associated with the popover.
+
+Associating a popover with a control using the `source` option creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties.
 
 ### Return value
 

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

@@ -21,15 +21,27 @@ 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, the control button or link associated with the popover.
+
+Associating a popover with a control using the `source` option creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties.
 
 ### Return value
 

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

@@ -12,6 +12,8 @@ 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.
 
+Associating a popover with a control using the `popoverTargetElement` property creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties.
+
 ## 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")}}

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

@@ -65,7 +65,7 @@ You can see the behavior described above in action in our [Multiple auto popover
 
 ## Using manual popover state
 
-The alternative to auto state is **manual state**, achieved by setting `popover="manual"` on your popover element:
+One alternative to auto state is **manual state**, achieved by setting `popover="manual"` on your popover element:
 
 ```html
 <div id="mypopover" popover="manual">Popover content</div>
@@ -190,6 +190,103 @@ There are three different ways to create nested popovers:
 
 See our [Nested popover menu example](https://mdn.github.io/dom-examples/popover-api/nested-popovers/) ([source](https://github.com/mdn/dom-examples/tree/main/popover-api/nested-popovers)) for an example. You'll notice that quite a few event handlers have been used to display and hide the subpopover appropriately during mouse and keyboard access, and also to hide both menus when an option is selected from either. Depending on how you handle loading of new content, either in an SPA or multi-page website, some of all of these may not be necessary, but they have been included in this demo for illustrative purposes.
 
+## Using "hint" popover state
+
+There is a third type of popover you can create — **hint popovers**, designated by setting `popover="hint"` on your popover element. `hint` popovers are similar to `auto` popovers, but with a significant difference. They can be light-dismissed, but they do not light-dismiss `auto` popovers when shown, only `hint` popovers.
+
+This is useful for situations where, for example, you have toolbar buttons that can be pressed to show UI popovers, but you also want to reveal tooltips when the buttons are hovered, without dismissing the UI popovers.
+
+`hint` popovers tend to be 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). When clicking on a button, the click itself would cause an open `auto` popover to light-dismiss.
+
+See our [popover hint demo](https://mdn.github.io/dom-examples/popover-api/popover-hint/) ([source](https://github.com/mdn/dom-examples/tree/main/popover-api/popover-hint)) for an example that behaves exactly as described above. The demo features a button bar; when pressed, the buttons show popup sub-menus inside which further options can be selected. However, when hovered over or focused, the buttons also show tooltips to give the user an idea of what each button does.
+
+In the below sections, we'll walk through all the important parts of the code.
+
+### Creating the sub-menus with `popover="auto"`
+
+The popup sub-menus are created declaratively, using `auto` popovers.
+
+First, the control buttons:
+
+```html
+<section id="button-bar">
+  <button popovertarget="submenu-1" popovertargetaction="toggle" id="menu-1">
+    Menu A
+  </button>
+
+  <button popovertarget="submenu-2" popovertargetaction="toggle" id="menu-2">
+    Menu B
+  </button>
+
+  <button popovertarget="submenu-3" popovertargetaction="toggle" id="menu-3">
+    Menu C
+  </button>
+</section>
+```
+
+Now, the popovers themselves:
+
+```html
+<div id="submenu-1" popover="auto">
+  <button>Option A</button><br /><button>Option B</button>
+</div>
+<div id="submenu-2" popover="auto">
+  <button>Option A</button><br /><button>Option B</button>
+</div>
+<div id="submenu-3" popover="auto">
+  <button>Option A</button><br /><button>Option B</button>
+</div>
+```
+
+### Creating the tooltips with `popover="hint"`
+
+The sub-menu popovers work fine as they are, opening when the toolbar buttons are clicked, but how do we also show tooltips on button hover/focus? First, we create the tooltips in HTML, using `hint` popovers:
+
+```html
+<div id="tooltip-1" class="tooltip" popover="hint">Tooltip A</div>
+<div id="tooltip-2" class="tooltip" popover="hint">Tooltip B</div>
+<div id="tooltip-3" class="tooltip" popover="hint">Tooltip C</div>
+```
+
+To control the showing/hiding, we need to use JavaScript. First of all, we grab references to the `hint` popovers and the control buttons in two separate {{domxref("NodeList")}}s using {{domxref("Document.querySelectorAll()")}}:
+
+```js
+const tooltips = document.querySelectorAll(".tooltip");
+const btns = document.querySelectorAll("#button-bar button");
+```
+
+Next, we create a function, `addEventListeners()`, which sets four event listeners (via {{domxref("EventTarget.addEventListener()")}}) on a given {{htmlelement("button")}}, chosen by grabbing the `<button>` at a specific index value of the `btns` `NodeList`. The functions act on the `hint` popover at the same index value of the `tooltips` `NodeList`, allowing us to keep the buttons and the tooltips in sync — showing/hiding the correct tooltip when a button is interacted with.
+
+The event listeners [show](/en-US/docs/Web/API/HTMLElement/showPopover) the popover on [`mouseover`](/en-US/docs/Web/API/Element/mouseover_event) and [`focus`](/en-US/docs/Web/API/Element/focus_event), and [hide](/en-US/docs/Web/API/HTMLElement/hidePopover) the popover on [`mouseout`](/en-US/docs/Web/API/Element/mouseout_event) and [`blur`](/en-US/docs/Web/API/Element/blur_event), meaning that the tooltips can be accessed via mouse and keyboard.
+
+```js
+function addEventListeners(i) {
+  btns[i].addEventListener("mouseover", () => {
+    tooltips[i].showPopover({ source: btns[i] });
+  });
+
+  btns[i].addEventListener("mouseout", () => {
+    tooltips[i].hidePopover();
+  });
+
+  btns[i].addEventListener("focus", () => {
+    tooltips[i].showPopover({ source: btns[i] });
+  });
+
+  btns[i].addEventListener("blur", () => {
+    tooltips[i].hidePopover();
+  });
+}
+```
+
+Finally, we use a [`for`](/en-US/docs/Web/JavaScript/Reference/Statements/for) loop to iterate through the `<buttons>` in the `btns` `NodeList`, calling the `addEventListeners()` function for each one so that all of them have the desired event listeners set.
+
+```js
+for (let i = 0; i < btns.length; i++) {
+  addEventListeners(i);
+}
+```
+
 ## Styling popovers
 
 The popover API has some related CSS features available that are worth looking at.
@@ -239,6 +336,14 @@ The {{cssxref("::backdrop")}} pseudo-element is a full-screen element placed dir
 
 See our [Popover blur background example](https://mdn.github.io/dom-examples/popover-api/blur-background/) ([source](https://github.com/mdn/dom-examples/tree/main/popover-api/blur-background)) for an idea of how this renders.
 
+### Implicit popover anchor associations
+
+Associating a popover with a control using the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) and [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attributes creates an implicit anchor reference between the two, as does programmatically associating a popover action such as {{domxref("HTMLElement.showPopover", "showPopover()")}} with a control using the `source` option.
+
+This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties.
+
+For an example that uses this implicit association, see the [Using "hint" popover state](/en-US/docs/Web/API/Popover_API/Using#using_hint_popover_state) section above.
+
 ## Animating popovers
 
 Popovers are set to `display: none;` when hidden and `display: block;` when shown, as well as being removed from / added to the {{glossary("top layer")}} and the [accessibility tree](/en-US/docs/Web/Performance/How_browsers_work#building_the_accessibility_tree). Therefore, for popovers to be animated, the {{cssxref("display")}} property needs to be animatable. [Supporting browsers](/en-US/docs/Web/CSS/display#browser_compatibility) animate `display` with a variation on the [discrete animation type](/en-US/docs/Web/CSS/CSS_animated_properties#discrete). Specifically, the browser will flip between `none` and another value of `display` so that the animated content is shown for the entire animation duration. So, for example:

files/en-us/web/css/anchor-name/index.md

@@ -40,7 +40,7 @@ anchor-name: unset;
 
 ## Description
 
-To position an element relative to an anchor element, the positioned element requires three features: an association, a position, and a location. The `anchor-name` and {{cssxref("position-anchor")}} properties provide the association.
+To position an element relative to an anchor element, the positioned element requires three features: an association, a position, and a location. The `anchor-name` and {{cssxref("position-anchor")}} properties provide an explicit association.
 
 The anchor element accepts one or more `<dashed-ident>` anchor names set on it via the `anchor-name` property. When one of those names is then set as the value of the `position-anchor` property of an element that has its {{cssxref("position")}} set to `absolute` or `fixed`, the two elements are associated. The two elements become tethered by setting a location on the associated element relative to the anchor, making it an "anchor-positioned" element.