1. 6.13 Interest invokers
      1. 6.13.1 The interestfor attribute
      2. 6.13.2 The InterestEvent interface
      3. 6.13.3 Processing model
      4. 6.13.4 User interaction

6.13 Interest invokers

An interest invoker is an a, area, or button element with the interestfor attribute set.

6.13.1 The interestfor attribute

The interestfor attribute allows authors to set up an invoker relationship between the triggering element and a separate target element such as a popover. With this arrangement, when the user shows interest in the triggering element (e.g., by hovering or focusing it), the target element will have an interest event fired on it. If the target is a popover with a popover visibility state of hidden, this will show the popover. When the user loses interest (e.g., by no longer hovering or focusing the invoker or target) a loseinterest event is fired. If the target is a popover it will be hidden.

If specified, the interestfor attribute value must be the ID of an element in the same tree as the element with the interestfor attribute.

DOM interface: 
interface mixin InterestInvokerElement {
  [CEReactions] attribute Element? interestForElement;
};

The interestForElement IDL attribute must reflect the interestfor attribute.

The following demonstrates how one might show a tooltip for a button using the interestfor attribute to associate the button with a popover representing the tooltip.

<button interestfor=tooltip>
 Click me
</button>

<div popover=hint id=tooltip>
 I will appear when the user shows interest in the button
</div>

Every HTML element has an element-or-null active interest target, initially null.

Every HTML element has a pending interest change handle, which is a unique internal value or null, initially null.

The pending interest change handle is used to abort steps that run after a timeout.

Every element has an element-or-null active interest source, initially null.

When non-null, an element's active interest target is a cached result of getting the interestfor-associated element and the target's active interest source points back to the source. This is a convenience that makes it easier to handle tree modifications that break the association between source and target.

6.13.2 The InterestEvent interface

[Exposed=Window]
interface InterestEvent : Event {
  constructor(DOMString type, InterestEventInit eventInitDict);
  readonly attribute Element source;
};

dictionary InterestEventInit : EventInit {
  required Element source;
};
event.source

Set to the interest invoker that triggered interest.

The source attribute must return the value it was initialized to.

6.13.3 Processing model

To handle interest change for an element element and a boolean show:

  1. If element's active interest source is not null, handle interest change for element's active interest source and show.

    User interactions such as hovering or focusing an interest target have the same effect as interactions with the invoker. This prevents interest from being lost while the user is interacting with the target. Since an element can simultaneously be both an invoker and a target, the following steps are still run.

  2. If element is not an interest invoker, then return.

  3. Let global be element's relevant global object.

  4. Let target be the result of running element's get the interestfor-associated element.

  5. If target is null, then return.

  6. Let delayProperty be 'interest-show-delay' if show is true, otherwise 'interest-hide-delay'.

  7. Let delay be the computed value of delayProperty on element, interpreted as a number of milliseconds.

  8. If delay is negative, infinite, or NaN, then return.

  9. Let uniqueHandle be null.

  10. Let task be a task that runs the following substeps:

    1. Assert: uniqueHandle is a unique internal value, not null.

    2. If uniqueHandle is not in element's pending interest change handle, then abort these steps.

    3. Set element's pending interest change handle to null.

    4. If element is not connected, then abort these steps.

    5. If element's node document is not fully active, then abort these steps.

    6. If the result of running element's get the interestfor-associated element is not target, then abort these steps.

    7. If show is true, then gain interest in element with target.

    8. Otherwise, lose interest in element with target.

  11. Let completionStep be an algorithm step which queues a global task on the timer task source given global to run task.

  12. Set uniqueHandle to the result of running steps after a timeout given global, "interest change", timeout, and completionStep.

  13. Set element's pending interest change handle to uniqueHandle.

To gain interest in an HTML element invoker given an element target:

  1. Assert: invoker is an a, area, or button element.

  2. Assert: the result of running invoker's get the interestfor-associated element is target.

  3. If invoker's active interest target is not null:

    1. If invoker's active interest target is target, then set invoker's pending interest change handle to null and return.

      Interest has already been gained for the correct target and there is nothing to do except to cancel pending tasks.

    2. If the result of losing interest in invoker given invoker's active interest target is false, then return.

      This fires the loseinterest event, which could be canceled.

  4. Assert: invoker's active interest target is null.

  5. If target's active interest source is not null:

    1. If the result of losing interest in target's active interest source given target is false, then return.

      This fires the loseinterest event, which could be canceled.

  6. Assert: target's active interest source is null.

  7. Let continue be the result of firing an event named interest at target, using InterestEvent, with the cancelable attribute initialized to true, and the source attribute initialized to invoker.

  8. If continue is false, then return.

  9. Set invoker's active interest target to target.

  10. Set target's active interest source to invoker.

  11. If target's popover visibility state is hidden, then run show popover given target, false, and invoker.

To lose interest in an HTML element invoker given an element target:

  1. Assert: invoker is an a, area, or button element.

  2. Assert: the result of running invoker's get the interestfor-associated element is target.

  3. Let continue be the result of firing an event named loseinterest at target, using InterestEvent, with the cancelable and composed attributes initialized to true, and the source attribute initialized to invoker.

  4. If continue is false, then return false.

  5. Reset interest state for invoker.

  6. If target's popover visibility state is showing, then hide popover given invoker, false, true, and false.

  7. Return true.

To reset interest state for an HTML element invoker:

  1. Let target be invoker's active interest target.

  2. Set invoker's active interest target to null.

  3. Set target's active interest source to null.

  4. Set invoker's pending interest change handle to null.

The following attribute change steps, given element, localName, oldValue, value, and namespace, are used for a, area, and button elements:

  1. If namespace is not null, then return.

  2. If localName is not interestfor, then return.

  3. If value is oldValue, then return.

  4. If element's active interest target is not null, then reset interest state for element.

The following attribute change steps, given element, localName, oldValue, value, and namespace, are used for all elements:

  1. If namespace is not null, then return.

  2. If localName is not id, then return.

  3. If value is oldValue, then return.

  4. If element's active interest source is not null, then reset interest state for element's active interest source.

6.13.4 User interaction

When the user designates an element element with a pointing device, the user agent must queue a task on the user interaction task source to handle interest change for element and true.

When the user no longer designates an element element with a pointing device, the user agent must queue a task on the user interaction task source to handle interest change for element and false.

The tasks queued on the user interaction task source in this section must be queued after any tasks that fire events such as mouseover and mouseout or that affect the :hover pseudo-class.

This means that when the interest and loseinterest events fire, any event handlers see the state after the change.

Keyboard interactions are handled in the focus update steps.

For input modalities other than pointing devices and keyboards, the user agent should provide the ability for the user to indicate interest.