Technical review: Document interest invokers

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

@@ -29,6 +29,8 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._
   - : A string that is the result of parsing the [`href`](/en-US/docs/Web/HTML/Reference/Elements/a#href) HTML attribute relative to the document, containing a valid URL of a linked resource.
 - {{domxref("HTMLAnchorElement.hreflang")}}
   - : A string that reflects the [`hreflang`](/en-US/docs/Web/HTML/Reference/Elements/a#hreflang) HTML attribute, indicating the language of the linked resource.
+- {{domxref("HTMLAnchorElement.interestForElement")}} {{experimental_inline}}
+  - : Gets or sets the interest invoker target element, in cases where the associated {{htmlelement("a")}} element is specified as an [interest invoker](/en-US/docs/Web/API/Popover_API/Interest_invokers#creating_an_interest_invoker).
 - {{domxref("HTMLAnchorElement.origin")}} {{ReadOnlyInline}}
   - : Returns a string containing the origin of the URL, that is its scheme, its domain and its port.
 - {{domxref("HTMLAnchorElement.password")}}

files/en-us/web/api/htmlanchorelement/interestforelement/index.md

@@ -0,0 +1,66 @@
+---
+title: "HTMLAnchorElement: interestForElement property"
+short-title: interestForElement
+slug: Web/API/HTMLAnchorElement/interestForElement
+page-type: web-api-instance-property
+browser-compat: api.HTMLAnchorElement.interestForElement
+---
+
+{{ApiRef("HTML DOM")}}
+
+The **`interestForElement`** property of the {{domxref("HTMLAnchorElement")}} interface gets or sets the interest invoker target element, in cases where the associated {{htmlelement("a")}} element is specified as an interest invoker.
+
+See [Creating an interest invoker](/en-US/docs/Web/API/Popover_API/Interest_invokers#creating_an_interest_invoker) for more details.
+
+## Value
+
+An {{domxref("Element")}} object instance, or `null` if the associated `<a>` element has no interest invoker target.
+
+## Examples
+
+### Basic `interestForElement` usage
+
+In this example, we use an `<a>` element's `interestForElement` property to set its interest invoker target element and then retrieve its target element's `tagName`. The `tagName` is then printed into the `<a>` element's text content.
+
+#### HTML
+
+We include an `<a>` element and a `<div>` element. We turn the `<div>` element into a popover by setting a `popover` attribute on it.
+
+```html live-sample___basic-interest-invoker
+<a href="#">a link</a>
+<div id="mypopover" popover>I am a <code>&lt;div&gt;</code> element.</div>
+```
+
+#### JavaScript
+
+We grab a reference to the `<a>` and `<div>` elements in script, then declare an interest invoker/target relationship between the `<a>` and the `<div>` by setting the `<a>` element's `interestForElement` property equal to a reference to the `<div>`. We then set the `<a>` element's text content equal to a string containing the target element's `tagName`, retrieved via `invoker.interestForElement.tagName`.
+
+```js live-sample___basic-interest-invoker
+const invoker = document.querySelector("a");
+const popover = document.querySelector("div");
+
+invoker.interestForElement = popover;
+
+invoker.textContent = `My target is a ${invoker.interestForElement.tagName} element`;
+```
+
+#### Result
+
+The example renders like this:
+
+{{embedlivesample("basic-interest-invoker", "100%", "100")}}
+
+Try showing interest in the link (for example, by hovering or focusing it) to make the `<div>` appear.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Using interest invokers](/en-US/docs/Web/API/Popover_API/Interest_invokers)
+- [The Popover API](/en-US/docs/Web/API/Popover_API)

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

@@ -29,6 +29,8 @@ _Inherits properties from its parent {{domxref("HTMLElement")}}._
   - : A string containing the hostname in the referenced URL.
 - {{domxref("HTMLAreaElement.href")}}
   - : A string containing that reflects the [`href`](/en-US/docs/Web/HTML/Reference/Elements/area#href) HTML attribute, containing a valid URL of a linked resource.
+- {{domxref("HTMLAreaElement.interestForElement")}} {{experimental_inline}}
+  - : Gets or sets the interest invoker target element, in cases where the associated {{htmlelement("area")}} element is specified as an [interest invoker](/en-US/docs/Web/API/Popover_API/Interest_invokers#creating_an_interest_invoker).
 - {{domxref("HTMLAreaElement.noHref")}} {{deprecated_inline}}
   - : A boolean flag indicating if the area is inactive (`true`) or active (`false`).
 - {{domxref("HTMLAreaElement.origin")}} {{ReadOnlyInline}}

files/en-us/web/api/htmlareaelement/interestforelement/index.md

@@ -0,0 +1,77 @@
+---
+title: "HTMLAreaElement: interestForElement property"
+short-title: interestForElement
+slug: Web/API/HTMLAreaElement/interestForElement
+page-type: web-api-instance-property
+browser-compat: api.HTMLAreaElement.interestForElement
+---
+
+{{ApiRef("HTML DOM")}}
+
+The **`interestForElement`** property of the {{domxref("HTMLAreaElement")}} interface gets or sets the interest invoker target element, in cases where the associated {{htmlelement("area")}} element is specified as an interest invoker.
+
+See [Creating an interest invoker](/en-US/docs/Web/API/Popover_API/Interest_invokers#creating_an_interest_invoker) for more details.
+
+## Value
+
+An {{domxref("Element")}} object instance, or `null` if the associated `<area>` element has no interest invoker target.
+
+## Examples
+
+### Basic `interestForElement` usage
+
+In this example, we use an `<area>` element's `interestForElement` property to set its interest invoker target element and then retrieve its target element's `tagName`. The `tagName` is then printed into the `<area>` element's text content.
+
+#### HTML
+
+We include an `<area>` element and a `<div>` element. We turn the `<div>` element into a popover by setting a `popover` attribute on it.
+
+```html live-sample___basic-interest-invoker
+<map>
+  <area href="#" shape="default" />
+</map>
+<div id="mypopover" popover>I am a <code>&lt;div&gt;</code> element.</div>
+```
+
+```css hidden live-sample___basic-interest-invoker
+map {
+  width: 200px;
+  height: 100px;
+  background-color: pink;
+  padding: 5px;
+}
+```
+
+#### JavaScript
+
+We grab references to the `<area>` and `<div>` elements in script, then declare an interest invoker/target relationship between the `<area>` and the `<div>` by setting the `<area>` element's `interestForElement` property equal to a reference to the `<div>`. We then set the `<area>` element's text content equal to a string containing the target element's `tagName`, retrieved via `invoker.interestForElement.tagName`.
+
+```js live-sample___basic-interest-invoker
+const invoker = document.querySelector("area");
+const popover = document.querySelector("div");
+
+invoker.interestForElement = popover;
+
+invoker.textContent = `My target is a ${invoker.interestForElement.tagName} element`;
+```
+
+#### Result
+
+The example renders like this:
+
+{{embedlivesample("basic-interest-invoker", "100%", "100")}}
+
+Try showing interest in the area (for example, by hovering or focusing it) to make the `<div>` appear.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Using interest invokers](/en-US/docs/Web/API/Popover_API/Interest_invokers)
+- [The Popover API](/en-US/docs/Web/API/Popover_API)

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

@@ -34,6 +34,8 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._
   - : A boolean value indicating that the form is not to be validated when it is submitted. If specified, this attribute overrides the [`novalidate`](/en-US/docs/Web/HTML/Reference/Elements/form#novalidate) attribute of the {{HTMLElement("form")}} element that owns this element.
 - {{domxref("HTMLButtonElement.formTarget")}}
   - : A string reflecting a name or keyword indicating where to display the response received after submitting the form. If specified, this attribute overrides the [`target`](/en-US/docs/Web/HTML/Reference/Elements/form#target) attribute of the {{HTMLElement("form")}} element that owns this element.
+- {{domxref("HTMLButtonElement.interestForElement")}} {{experimental_inline}}
+  - : Gets or sets the interest invoker target element, in cases where the associated {{htmlelement("button")}} element is specified as an [interest invoker](/en-US/docs/Web/API/Popover_API/Interest_invokers#creating_an_interest_invoker).
 - {{domxref("HTMLButtonElement.labels")}} {{ReadOnlyInline}}
   - : A {{domxref("NodeList")}} that represents a list of {{HTMLElement("label")}} elements that are labels for this button.
 - {{domxref("HTMLButtonElement.name")}}

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

@@ -0,0 +1,66 @@
+---
+title: "HTMLButtonElement: interestForElement property"
+short-title: interestForElement
+slug: Web/API/HTMLButtonElement/interestForElement
+page-type: web-api-instance-property
+browser-compat: api.HTMLButtonElement.interestForElement
+---
+
+{{ApiRef("HTML DOM")}}
+
+The **`interestForElement`** property of the {{domxref("HTMLButtonElement")}} interface gets or sets the interest invoker target element, in cases where the associated {{htmlelement("button")}} element is specified as an interest invoker.
+
+See [Creating an interest invoker](/en-US/docs/Web/API/Popover_API/Interest_invokers#creating_an_interest_invoker) for more details.
+
+## Value
+
+An {{domxref("Element")}} object instance, or `null` if the associated `<button>` element has no interest invoker target.
+
+## Examples
+
+### Basic `interestForElement` usage
+
+In this example, we use a `<button>` element's `interestForElement` property to set its interest invoker target element and then retrieve its target element's `tagName`. The `tagName` is then printed into the `<button>` element's text content.
+
+#### HTML
+
+We include a `<button>` element and a `<div>` element. We turn the `<div>` element into a popover by setting a `popover` attribute on it.
+
+```html live-sample___basic-interest-invoker
+<button href="#">a button</button>
+<div id="mypopover" popover>I am a <code>&lt;div&gt;</code> element.</div>
+```
+
+#### JavaScript
+
+We grab references to the `<button>` and `<div>` elements in script, then declare an interest invoker/target relationship between the `<button>` and the `<div>` by setting the `<button>` element's `interestForElement` property equal to a reference to the `<div>`. We then set the button's text content equal to a string containing the target element's `tagName`, retrieved via `invoker.interestForElement.tagName`.
+
+```js live-sample___basic-interest-invoker
+const invoker = document.querySelector("button");
+const popover = document.querySelector("div");
+
+invoker.interestForElement = popover;
+
+invoker.textContent = `My target is a ${invoker.interestForElement.tagName} element`;
+```
+
+#### Result
+
+The example renders like this:
+
+{{embedlivesample("basic-interest-invoker", "100%", "100")}}
+
+Try showing interest in the button (for example, by hovering or focusing it) to make the `<div>` appear.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Using interest invokers](/en-US/docs/Web/API/Popover_API/Interest_invokers)
+- [The Popover API](/en-US/docs/Web/API/Popover_API)

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

@@ -140,6 +140,13 @@ _Also, inherits events from its parent, {{DOMxRef("Element")}}._
 - {{DOMxRef("HTMLElement/drop_event", "drop")}}
   - : This event is fired when an element or text selection is dropped on a valid drop target.
 
+### Interest invoker events
+
+- {{domxref("HTMLElement.interest_event", "interest")}} {{experimental_inline}}
+  - : Fired on an [interest invoker](/en-US/docs/Web/API/Popover_API/Interest_invokers)'s target element when interest is shown, allowing code to be run in response.
+- {{domxref("HTMLElement.loseinterest_event", "loseinterest")}} {{experimental_inline}}
+  - : Fired on an interest invoker's target element when interest is lost, allowing code to be run in response.
+
 ### Toggle events
 
 - {{DOMxRef("HTMLElement/beforetoggle_event", "beforetoggle")}}

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

@@ -0,0 +1,86 @@
+---
+title: "HTMLElement: interest event"
+slug: Web/API/HTMLElement/interest_event
+page-type: web-api-event
+browser-compat: api.HTMLElement.interest_event
+---
+
+{{APIRef("HTML DOM")}}
+
+The **`interest`** event of the {{domxref("HTMLElement")}} interface is fired on an [interest invoker](/en-US/docs/Web/API/Popover_API/Interest_invokers)'s target element when interest is shown, allowing code to be run in response.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js-nolint
+addEventListener("interest", (event) => { })
+
+oninterest = (event) => { }
+```
+
+## Event type
+
+An {{domxref("InterestEvent")}}. Inherits from {{domxref("Event")}}.
+
+{{InheritanceDiagram("InterestEvent")}}
+
+## Examples
+
+### Basic interest invoker event usage
+
+In this example, we use the `interest` and `loseinterest` events to report when interest is being shown and lost on a {{htmlelement("button")}} element interest invoker. We do this by printing messages into the {{htmlelement("p")}} target element's text content.
+
+#### HTML
+
+We set up a relationship between the `<button>` element interest invoker and its target `<p>` element by setting the `<button>` element's `interestfor` attribute equal to the `<p>` element's `id`.
+
+```html live-sample___basic-interest-invoker
+<button href="#" interestfor="mytarget">Interest invoker</button>
+<p id="mytarget">Interest not being shown.</p>
+```
+
+#### JavaScript
+
+We grab a reference to the `<button>` element and its target element (via its {{domxref("HTMLButtonElement.interestForElement", "interestForElement")}} property).
+
+```js live-sample___basic-interest-invoker
+const invoker = document.querySelector("[interestfor]");
+const target = invoker.interestForElement;
+```
+
+We then set two event listeners on the target element, for the `interest` and `loseinterest` events.
+
+- When interest is shown, we print a message into the target `<p>` element's text context to say that interest has been shown via the `<button>` element. Note how you can get a reference to the interest invoker via the event object's {{domxref("InterestEvent.source", "source")}} property.
+- When interest is lost, we report that, again via a message printed to the paragraph text.
+
+```js live-sample___basic-interest-invoker
+target.addEventListener("interest", (e) => {
+  target.textContent = `Interest being shown via the ${e.source.tagName} element.`;
+});
+
+target.addEventListener("loseinterest", () => {
+  target.textContent = `Interest lost.`;
+});
+```
+
+#### Result
+
+The example renders like this:
+
+{{embedlivesample("basic-interest-invoker", "100%", "100")}}
+
+Try showing/losing interest in the button (for example, by hovering or focusing it) to see how the `<p>` text changes.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Popover API](/en-US/docs/Web/API/Popover_API)
+- [Using interest invokers](/en-US/docs/Web/API/Popover_API/Interest_invokers)