Accessibility popover guidance

Supersedes #8791. Fixes #8714.

source

@@ -81768,6 +81768,86 @@ dictionary <dfn dictionary>DragEventInit</dfn> : <span>MouseEventInit</span> {
   won't be rendered until it becomes shown, at which point it will be rendered on top of other page
   content.</p>
 
+  <div class="example">
+   <p>The <code data-x="attr-popover">popover</code> attribute is a global attribute that allows
+   authors flexibility to ensure popover functionality can be applied to elements with the most
+   relevant semantics.</p>
+
+   <p>The following demonstrates how one might create a popover sub-navigation list of
+   links, within the global navigation for a website.</p>
+
+   <pre><code class="html">&lt;ul>
+  &lt;li>
+    &lt;a href=...>All Products&lt;/a>
+    &lt;button popovertarget=sub-nav>
+     &lt;img src=down-arrow.png alt="Product pages">
+    &lt;/button>
+    &lt;ul popover id=sub-nav>
+     &lt;li>&lt;a href=...>Shirts&lt;/a>
+     &lt;li>&lt;a href=...>Shoes&lt;/a>
+     &lt;li>&lt;a href=...>Hats etc.&lt;/a>
+    &lt;/ul>
+  &lt;/li>
+  &lt;!-- other list items and links here -->
+&lt;/ul></code></pre>
+  </div>
+
+  <p>When using <code data-x="attr-popover">popover</code> on elements without accessibility
+  semantics, for instance the <code>div</code> element, authors should use the appropriate ARIA
+  attributes to ensure the popover is accessible.</p>
+
+  <div class="example">
+   <p>The following shows the baseline markup to create a custom menu popover, where the first
+   menuitem will receive keyboard focus when the popover is invoked due to the use of the
+   <code data-x="">autofocus</code> attribute. Navigating the menuitems by arrow keys, and
+   activation behaviors would still need author scripting.</p>
+
+   <pre><code class="html">&lt;button popovertarget=menu aria-haspopup=menu>Actions&lt;/button>
+ &lt;div role=menu id=menu popover>
+  &lt;button role=menuitem tabindex=-1 autofocus>Edit&lt;/button>
+  &lt;button role=menuitem tabindex=-1>Hide&lt;/button>
+  &lt;button role=menuitem tabindex=-1>Delete&lt;/button>
+&lt;/div></code></pre>
+
+   <p>A popover can be useful for rendering a status message, confirming the action performed by
+   the user. The following demonstrates how one could reveal a popover in an <code>output</code>
+   element.</p>
+
+   <pre><code class="html">&lt;button id=submit>Submit&lt;/button>
+&lt;p>&lt;output>&lt;span popover=manual>&lt;/span>&lt;/output>&lt;/p>
+
+&lt;script>
+ const sBtn = document.getElementById('submit');
+ const outSpan = document.querySelector('output [popover=manual]');
+ let successMessage;
+ let errorMessage;
+
+ /* define logic for determining success of action
+  and determining the appropriate success or error
+  messages to use */
+
+ sBtn.addEventListener('click', ()=> {
+  if ( success ) {
+   outSpan.textContent = successMessage;
+  }
+  else {
+   outSpan.textContent = errorMessage;
+  }
+  outSpan.showPopover();
+
+  setTimeout(function () {
+   outSpan.hidePopover();
+  }, 10000);
+ });
+&lt;script></code></pre>
+  </div>
+
+  <p class="note">Inserting a popover element into an <code>output</code> element will generally
+  cause screen readers to announce the content when it becomes visible. Depending on the complexity
+  or frequency of the content, this could be either useful or annoying to users of these
+  assistive technologies. Keep this in mind when using the <code>output</code> element or other
+  ARIA live regions to ensure the best user experience.</p>
+
   <p>The <code data-x="attr-popover">popover</code> attribute is an <span>enumerated
   attribute</span> with the following keywords and states:</p>
 
@@ -82450,29 +82530,35 @@ dictionary <dfn dictionary>DragEventInit</dfn> : <span>MouseEventInit</span> {
   default">missing value default</i> are both the <span
   data-x="attr-popovertargetaction-toggle-state">toggle</span> state.</p>
 
+  <p class="note">Whenever possible ensure the popover element is placed immediately after its
+  triggering element in the DOM. Doing so will help ensure that the popover is exposed in a logical
+  programmatic reading order for users of assistive technology, such as screen readers.</p>
+
   <div class="example">
    <p>The following shows how the <code data-x="attr-popovertarget">popovertarget</code> attribute
    in combination with the <code data-x="attr-popovertargetaction">popovertargetaction</code>
-   attribute can be used to show a popover:</p>
+   attribute can be used to show and close a popover:</p>
 
-   <pre><code class="html">&lt;div popover=auto id="foo">
-  This is a popover!
-&lt;/div>
-
-&lt;button popovertarget="foo" popovertargetaction="show">
+   <pre><code class="html">&lt;button popovertarget="foo" popovertargetaction="show">
   Show a popover
-&lt;/button></code></pre>
+&lt;/button>
 
-   <p>The following shows how the <code data-x="attr-popovertarget">popovertarget</code> attribute
-   can open and close a manual popover, which can't be closed with light dismiss:</p>
+&lt;article popover=auto id="foo">
+  This is a popover article!
+  &lt;button popovertarget="foo" popovertargetaction="close">Close&lt;/button>
+&lt;/article></code></pre>
 
-   <pre><code class="html">&lt;div popover=manual id="foo">
-  This is a popover!
-&lt;/div>
+   <p>If a <code data-x="attr-popovertargetaction">popovertargetaction</code> attribute is not
+   specified, the default action will be to toggle the associated popover. The following shows
+   how only specifying the <code data-x="attr-popovertarget">popovertarget</code> attribute on its
+   invoking button can toggle a manual popover between its opened and closed states. A manual
+   popover will not light dismiss:</p>
 
-&lt;button popovertarget="foo">
-  Show or hide a popover
-&lt;/button></code></pre>
+   <pre><code class="html">&lt;input type="button" popovertarget="foo" value="Toggle the popover">
+
+&lt;div popover=manual id="foo">
+  This is a popover!
+&lt;/div></code></pre>
   </div>
 
   <span data-x="concept-element-dom">DOM interface</span>: