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

6.13 The interestfor attribute

The interestfor attribute allows authors to set up a 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 interest source or target) a loseinterest event is fired. If the target is a popover with a popover visibility state of showing, 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 InterestForAttribute {
  [CEReactions, Reflect="interestfor"] attribute Element? interestForElement;
};

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>
 Hover or focus me to show the tooltip
</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 Document has an active interest sources set, a set of HTML elements, initially the empty set.

The active interest sources set holds all of the HTML elements in the document that have a non-null active interest target, in the order that interest was gained.

Every HTML element has a pending gain interest handle and a pending lose interest handle, which are both a unique internal value or null, initially null.

These handles are used to abort steps that run after a timeout, effectively canceling the tasks.

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.1 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 element that triggered interest.

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

6.13.2 Processing model

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

  1. If show is true:

    1. For each element upstream in element's recursive active interest sources:

      1. Set upstream's pending lose interest handle to null.

        This effectively cancels any pending task to lose interest for upstream. User interactions such as hovering or focusing an interest target or its descendants prevent those tasks for running, so that interest isn't lost while the user is interacting with the target.

  2. If element is not an a, area, or button element, then return.

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

  4. If target is null, then return.

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

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

  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 null.

  11. If show is true, set task to a task that runs the following substeps:

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

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

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

    4. If the interest ready check for element and target returns false, then abort these steps.

    5. Gain interest in element with target.

  12. Otherwise, set task to a task that runs the following substeps:

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

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

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

    4. If the interest ready check for element and target returns false, then abort these steps.

    5. Lose interest in element with target.

  13. Assert: task is a task.

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

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

  16. If show is true, set element's pending gain interest handle to uniqueHandle.

  17. Otherwise, set element's pending lose interest handle to uniqueHandle.

To find the recursive active interest sources given an element element, perform the following steps. They return a list of zero or more elements.

  1. Let sources be an empty list.

  2. Let pending be an empty queue.

  3. Enqueue element in pending.

  4. While pending is not empty:

    1. Let current be the result of dequeuing from pending.

    2. While current is not null:

      1. Let source be current's active interest source.

      2. If source is not null, source is not element, and sources does not contain source:

        1. Append source to sources.

        2. Enqueue source in pending.

      3. Set current to current's parent element.

  5. Return sources.

The recursive active interest sources algorithm finds all elements whose active interest target contains (inclusively) a given element, as well as any elements that indirect interest sources through the same condition applied recursively. In effect, all "upstream" interest sources in a graph of active interest target relations are found. Because cycles are possible, it is defined iteratively to avoid infinite loops.

The interest ready check for an HTML element source and an element target returns true if all of the following are true, and false otherwise:

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

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

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

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

    1. If source's active interest target is target, then set source's pending lose interest 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 source given source's active interest target is false, then return.

      This fires the loseinterest event.

    3. If the interest ready check for source and target returns false, then return.

  4. Assert: source'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.

    2. If the interest ready check for source and target returns false, then return.

  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 source.

  8. If continue is false, then return.

  9. If the interest ready check for source and target returns false, then return.

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

  11. Append source to source's node document's active interest sources set.

  12. Set target's active interest source to source.

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

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

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

  2. Assert: the result of running source'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 source.

  4. If continue is false, then return false.

  5. Reset interest state for source.

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

  7. Return true.

To reset interest state for an HTML element source:

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

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

  3. Remove source from source's node document's active interest sources set.

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

  5. Set source's pending gain interest handle to null.

  6. Set source's pending lose interest 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.3 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 above must be queued after any tasks that fire events such as mouseover and mouseout, or that affect the :hover pseudo-class.

Canceling events such as mouseover and mouseout does not prevent the above tasks from running.

When the user long presses an element element on a touch device, the user agent must queue a task on the user interaction task source to run the following steps:

  1. Fire any relevant events, per UI Events or other relevant specifications. [UIEVENTS]

  2. Let event be the Event object for any contextmenu event fired, or null if no such event was fired.

  3. Let showContextMenu be true if event is not null and its canceled flag is not set.

  4. If element is not an a, area, or button element, then abort these steps.

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

  6. If target is null, then abort these steps.

  7. Let gainInterestIfReady be the following step:

    1. If the interest ready check for element and target returns true, then gain interest in element with target.

  8. If showContextMenu is true, then provide an option in the context menu that, when selected, queues a task on the user interaction task source to run gainInterestIfReady.

  9. Otherwise, run gainInterestIfReady.

    There is no delay before gaining interest as the long press gesture already has an inherent delay.

Keyboard interactions are handled in the focus update steps.

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