Add imperative access to invoker, and connect to implicit anchor element

This includes two related changes:
 1. The `showPopover()` and `togglePopover()` methods now include an
    options bag that allows setting the popover invoker.
 2. Popover invokers (declaratively or imperatively set) now create
    an implicit anchor reference for that popover.

This new behavior was resolved in the [WHATWG/CSSWG/OpenUI joint task
force meeting on June 26, 2024](whatwg#9144 (comment)).

Closes whatwg#10442
Closes whatwg#10675

Author: mfreed7

source

@@ -4192,6 +4192,12 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
      <li><dfn data-x-href="https://drafts.csswg.org/css-contain/#content-visibility">'content-visibility'</dfn> property</li>
      <li><dfn data-x-href="https://drafts.csswg.org/css-contain/#propdef-content-visibility" data-x="content-visibility-auto">'auto'</dfn> value for <span>'content-visibility'</span></li>
     </ul>
+
+    <p>The following terms are defined in <cite>CSS Anchor Positioning</cite>: <ref>CSSANCHOR</ref></p>
+
+    <ul class="brief">
+     <li><dfn data-x-href="https://www.w3.org/TR/css-anchor-position-1/#implicit-anchor-element">implicit anchor element</dfn></li>
+    </ul>
    </dd>
 
 
@@ -11924,12 +11930,21 @@ interface <dfn interface>HTMLElement</dfn> : <span>Element</span> {
   <span>ElementInternals</span> <span data-x="dom-attachInternals">attachInternals</span>();
 
   // The popover API
-  undefined <span data-x="dom-showPopover">showPopover</span>();
+  undefined <span data-x="dom-showPopover">showPopover</span>(optional ShowPopoverOptions options);
   undefined <span data-x="dom-hidePopover">hidePopover</span>();
-  boolean <span data-x="dom-togglePopover">togglePopover</span>(optional boolean force);
+  boolean <span data-x="dom-togglePopover">togglePopover</span>(optional (TogglePopoverOptions or boolean) options);
   [<span>CEReactions</span>] attribute DOMString? <span data-x="dom-popover">popover</span>;
 };
 
+dictionary <dfn dictionary>TogglePopoverOptions</dfn> {
+  boolean force;
+  <span>HTMLElement</span> invoker;
+};
+
+dictionary <dfn dictionary>ShowPopoverOptions</dfn> {
+  <span>HTMLElement</span> invoker;
+};
+
 <span>HTMLElement</span> includes <span>GlobalEventHandlers</span>;
 <span>HTMLElement</span> includes <span>ElementContentEditable</span>;
 <span>HTMLElement</span> includes <span>HTMLOrSVGElement</span>;
@@ -85447,8 +85462,10 @@ dictionary <dfn dictionary>DragEventInit</dfn> : <span>MouseEventInit</span> {
    false.</dd>
   </dl>
 
-  <p>The <dfn method for="HTMLElement"><code data-x="dom-showPopover">showPopover()</code></dfn>
-  method steps are to run <span>show popover</span> given <span>this</span>, true, and null.</p>
+  <p>The
+  <dfn method for="HTMLElement"><code data-x="dom-showPopover">showPopover(<var>options</var>)</code></dfn>
+  method steps are to run <span>show popover</span> given <span>this</span>, true, and
+  <var>options</var>["<code data-x="">invoker</code>"].</p>
 
   <p>To <dfn>show popover</dfn>, given an <span data-x="HTML elements">HTML element</span>
   <var>element</var>, a boolean <var>throwExceptions</var>, and an <span data-x="HTML elements">HTML
@@ -85582,6 +85599,8 @@ dictionary <dfn dictionary>DragEventInit</dfn> : <span>MouseEventInit</span> {
 
    <li><p>Set <var>element</var>'s <span>popover invoker</span> to <var>invoker</var>.</p></li>
 
+   <li><p>Set <var>element</var>'s <span>implicit anchor element</span> to <var>invoker</var>.</p></li>
+
    <li><p>Run the <span>popover focusing steps</span> given <var>element</var>.</p></li>
 
    <li><p>If <var>shouldRestoreFocus</var> is true and <var>element</var>'s <code
@@ -85732,6 +85751,8 @@ dictionary <dfn dictionary>DragEventInit</dfn> : <span>MouseEventInit</span> {
 
      <li><p><span>Request an element to be removed from the top layer</span> given
      <var>element</var>.</p></li>
+
+     <li><p>Set <var>element</var>'s <span>implicit anchor element</span> to null.</p></li>
     </ol>
    </li>
 
@@ -85766,16 +85787,23 @@ dictionary <dfn dictionary>DragEventInit</dfn> : <span>MouseEventInit</span> {
   </ol>
 
   <p>The <dfn method for="HTMLElement"><code
-  data-x="dom-togglePopover">togglePopover(<var>force</var>)</code></dfn> method steps are:</p>
+  data-x="dom-togglePopover">togglePopover(<var>options</var>)</code></dfn> method steps are:</p>
 
   <ol>
+   <!-- TODO: I'm not sure what the correct way to handle a tri-state like this. This is generally
+   just trying to make it cleaner to use `force` in the algorithm. -->
+   <li><p>Let <var>force</var> be one of true, false, or unset, initially unset.</p></li>
+
+   <li><p>If <var>options</var> is a boolean, set <var>force</var> to <var>options</var>. Otherwise,
+   if <var>options</var>["<code data-x="">force</code>"] <span data-x="map exists">exists</span>,
+   set <var>force</var> to <var>options</var>["<code data-x="">force</code>"].</p></li>
+
    <li><p>If <span>this</span>'s <span>popover visibility state</span> is <span
-   data-x="popover-showing-state">showing</span>, and <var>force</var> is not present or false, then
-   run the <span>hide popover algorithm</span> given <span>this</span>, true, true, and
-   true.</p></li>
+   data-x="popover-showing-state">showing</span>, and <var>force</var> is unset or false, then run
+   the <span>hide popover algorithm</span> given <span>this</span>, true, true, and true.</p></li>
 
-   <li><p>Otherwise, if <var>force</var> is not present or true, then run <span>show popover</span>
-   given <span>this</span>, true, and null.</p></li>
+   <li><p>Otherwise, if <var>force</var> is unset or true, then run <span>show popover</span> given
+   <span>this</span>, true, and <var>options</var>["<code data-x="">invoker</code>"].</p></li>
 
    <li>
     <p>Otherwise:</p>
@@ -144093,6 +144121,9 @@ INSERT INTERFACES HERE
    <dt id="refsCSSALIGN">[CSSALIGN]</dt>
    <dd><cite><a href="https://w3c.github.io/csswg-drafts/css-align/">CSS Box Alignment</a></cite>, E. Etemad, T. Atkins. W3C.</dd>
 
+   <dt id="refsCSSANCHOR">[CSSANCHOR]</dt>
+   <dd><cite><a href="https://www.w3.org/TR/css-anchor-position-1/">CSS Anchor Positioning</a></cite>, T. Atkins, E. Etemad, I. Kilpatrick. W3C.</dd>
+
    <dt id="refsCSSANIMATIONS">[CSSANIMATIONS]</dt>
    <dd><cite><a href="https://w3c.github.io/csswg-drafts/css-animations/">CSS Animations</a></cite>, D. Jackson, D. Hyatt, C. Marrin, S. Galineau, L. Baron. W3C.</dd>