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/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/using/index.md

@@ -204,7 +204,9 @@ 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:
+The popup sub-menus are created declaratively, using `auto` popovers.
+
+First, the control buttons:
 
 ```html
 <section id="button-bar">
@@ -260,15 +262,15 @@ The event listeners [show](/en-US/docs/Web/API/HTMLElement/showPopover) the popo
 ```js
 function addEventListeners(i) {
   btns[i].addEventListener("mouseover", () => {
-    tooltips[i].showPopover();
+    tooltips[i].showPopover({ source: btns[i] });
   });
 
   btns[i].addEventListener("mouseout", () => {
     tooltips[i].hidePopover();
   });
 
   btns[i].addEventListener("focus", () => {
-    tooltips[i].showPopover();
+    tooltips[i].showPopover({ source: btns[i] });
   });
 
   btns[i].addEventListener("blur", () => {
@@ -334,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.
 

files/en-us/web/css/css_anchor_positioning/using/index.md

@@ -29,9 +29,9 @@ Historically, associating an element with another element and dynamically changi
 
 ## Associating anchor and positioned elements
 
-To associate an element with an anchor, you need to first declare which element is the anchor, and then specify which positioned element(s) to associate with that anchor. This can be done via CSS or via the HTML [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute.
+To associate an element with an anchor, you need to first declare which element is the anchor, and then specify which positioned element(s) to associate with that anchor. This can be done explicitly via CSS or via the HTML [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute, or in some cases, implicitly.
 
-### CSS-only method
+### Explicit CSS-only method
 
 To declare an element as an anchor with CSS, you need to set an anchor name on it via the {{cssxref("anchor-name")}} property. The anchor name needs to be a {{cssxref("dashed-ident")}}. In this example, we also set the anchor's {{cssxref("width")}} to `fit-content` to get a small square anchor, which better demonstrates the anchoring effect.
 
@@ -90,7 +90,7 @@ This will render as follows:
 
 The anchor and infobox are now associated, but for the moment you'll have to trust us on this. They are not tethered to each other yet — if you were to position the anchor and move it somewhere else on the page, it would move on its own, leaving the infobox in the same place. You'll see the actual tethering in action when we look at [positioning elements based on anchor position](#positioning_elements_relative_to_their_anchor).
 
-### HTML method
+### Explicit HTML method
 
 To associate a positioned element with an anchor in HTML, you can use the [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute. You need to give the anchor element an [`id`](/en-US/docs/Web/HTML/Global_attributes/id). The `anchor` attribute is then set on the anchor-positioned element, with a value equal to the `id` of the anchor element you want to associate it with.
 
@@ -141,7 +141,15 @@ This gives us the same result that we achieved earlier with CSS. We associated a
 > [!NOTE]
 > The [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute currently has less support than the CSS equivalent. See the [`anchor` attribute compatibility table](/en-US/docs/Web/HTML/Global_attributes/anchor#browser_compatibility) for more information.
 
-We've associated the two elements, but they are not yet tethered. To tether them together, the positioned element needs to be positioned relative to its anchor, which is done with CSS.
+### Implicit anchor association
+
+In some cases, an implicit anchor reference will be made between two elements, due to the semantic nature of their relationship. For example, when using the [Popover API](/en-US/docs/Web/API/Popover_API) to associate a popover with a control, an implicit anchor reference is made between the two. This can occur when:
+
+- Declaratively 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.
+- Programmatically associating a popover action such as {{domxref("HTMLElement.showPopover", "showPopover()")}} with a control using the `source` option.
+
+> [!NOTE]
+> The methods above associate an anchor with an element, but they are not yet tethered. To tether them together, the positioned element needs to be positioned relative to its anchor, which is done with CSS.
 
 ## Positioning elements relative to their anchor
 

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

@@ -40,7 +40,7 @@ position-anchor: unset;
 
 This property is only relevant to "positioned" elements — elements and pseudo elements that have a {{cssxref("position")}} of `absolute` or `fixed` set.
 
-To position an element relative to an anchor element, the positioned element requires three features: an association, a position, and a location. The `position-anchor` and {{cssxref("anchor-name")}} 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 `position-anchor` and {{cssxref("anchor-name")}} 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 positioned element's `position-anchor` property, the two elements are associated.
 

files/en-us/web/html/element/button/index.md

@@ -93,6 +93,8 @@ This element's attributes include the [global attributes](/en-US/docs/Web/HTML/G
 
   - : Turns a `<button>` element into a popover control button; takes the ID of the popover element to control as its value. See the {{domxref("Popover API", "Popover API", "", "nocode")}} landing page for more details.
 
+    Associating a popover with a control using the `popovertarget` attribute 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.
+
 - `popovertargetaction`
 
   - : Specifies the action to be performed on a popover element being controlled by a control `<button>`. Possible values are:

files/en-us/web/html/element/input/index.md

@@ -557,6 +557,8 @@ A few additional non-standard attributes are listed following the descriptions o
 
   - : Turns an `<input type="button">` element into a popover control button; takes the ID of the popover element to control as its value. See the {{domxref("Popover API", "Popover API", "", "nocode")}} landing page for more details.
 
+    Associating a popover with a control using the `popovertarget` attribute 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.
+
 - `popovertargetaction`
 
   - : Specifies the action to be performed on a popover element being controlled by a control `<input type="button">`. Possible values are:

files/en-us/web/html/global_attributes/popover/index.md

@@ -13,10 +13,12 @@ The **`popover`** [global attribute](/en-US/docs/Web/HTML/Global_attributes) is
 
 The `popover` attribute can take one of the following values:
 
-- `auto` (setting `popover` is equivalent to setting `popover="auto"`)
+- `auto`
 - `hint`
 - `manual`
 
+Setting an empty value for `popover` — `popover` or `popover=""` — is equivalent to setting `popover="auto"`.
+
 ## Description
 
 Popover elements are hidden via `display: none` until opened via an invoking/control element (i.e. a `<button>` or `<input type="button">` with a [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) attribute) or a {{domxref("HTMLElement.showPopover()")}} call.