From f5def65bda4d01a6a1e105fcf13fe45201b4f48a Mon Sep 17 00:00:00 2001
From: Joey Arhar <jarhar@chromium.org>
Date: Wed, 23 Mar 2022 09:15:21 -0700
Subject: [PATCH] Add hidden=until-found and beforematch

Closes #6040.

Explainer: https://github.com/WICG/display-locking/blob/main/explainers/hidden-content-explainer.md
---
 source | 232 +++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 203 insertions(+), 29 deletions(-)

diff --git a/source b/source
index 99240e590d6..436795b3cf0 100644
--- a/source
+++ b/source
@@ -3814,10 +3814,12 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
      <li><dfn data-x-href="https://drafts.csswg.org/css-pseudo/#file-selector-button-pseudo">'::file-selector-button'</dfn></li>
     </ul>
 
-    <p>The following term is defined in <cite>CSS Containment</cite>: <ref spec=CSSCONTAIN></p>
+    <p>The following terms are defined in <cite>CSS Containment</cite>: <ref spec=CSSCONTAIN></p>
 
     <ul class="brief">
      <li><dfn data-x-href="https://drafts.csswg.org/css-contain/#skips-its-contents">skips its contents</dfn></li>
+     <li><dfn data-x-href="https://drafts.csswg.org/css-contain/#containment-layout">layout
+     containment</dfn></li>
     </ul>
    </dd>
 
@@ -10405,7 +10407,7 @@ interface <dfn interface>HTMLElement</dfn> : <span>Element</span> {
   [<span>CEReactions</span>] attribute DOMString <span data-x="dom-dir">dir</span>;
 
   // <span>user interaction</span>
-  [<span>CEReactions</span>] attribute boolean <span data-x="dom-hidden">hidden</span>;
+  [<span>CEReactions</span>] attribute (boolean or unrestricted double or DOMString)? <span data-x="dom-hidden">hidden</span>;
   [<span>CEReactions</span>] attribute boolean <span data-x="dom-inert">inert</span>;
   undefined <span data-x="dom-click">click</span>();
   [<span>CEReactions</span>] attribute DOMString <span data-x="dom-accessKey">accessKey</span>;
@@ -11793,6 +11795,7 @@ https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%
 
   <ul class="brief">
    <li><code data-x="handler-onauxclick">onauxclick</code></li>
+   <li><code data-x="handler-onbeforematch">onbeforematch</code></li>
    <li><code data-x="handler-onblur">onblur</code>*</li>
    <li><code data-x="handler-oncancel">oncancel</code></li>
    <li><code data-x="handler-oncanplay">oncanplay</code></li>
@@ -75010,20 +75013,85 @@ END:VCARD</pre>
 
   <p>All <span>HTML elements</span> may have the <dfn element-attr for="html-global"><code
   data-x="attr-hidden">hidden</code></dfn> content attribute set. The <code
-  data-x="attr-hidden">hidden</code> attribute is a <span>boolean attribute</span>. When specified
-  on an element, it indicates that the element is not yet, or is no longer, directly relevant to the
-  page's current state, or that it is being used to declare content to be reused by other parts of
-  the page as opposed to being directly accessed by the user. <span w-nodev>User agents should not
-  render elements that have the <code data-x="attr-hidden">hidden</code> attribute specified. This
-  requirement may be implemented indirectly through the style layer. For example, an HTML+CSS user
-  agent could implement these requirements <a href="#hiddenCSS">using the rules suggested in the
-  Rendering section</a>.</span></p>
-
-  <p class="note">Because this attribute is typically implemented using CSS, it's also possible to
-  override it using CSS. For instance, a rule that applies 'display: block' to all elements will
-  cancel the effects of the <code data-x="attr-hidden">hidden</code> attribute. Authors therefore
-  have to take care when writing their style sheets to make sure that the attribute is still styled
-  as expected.</p>
+  data-x="attr-hidden">hidden</code> attribute is an <span>enumerated attribute</span>. The
+  following table lists the states for this attribute:</p>
+
+  <table>
+   <thead>
+    <tr>
+     <th>State
+     <th>Keywords
+   <tbody>
+    <tr>
+     <td><span data-x="attr-hidden-until-found-state">Until found state</span>
+     <td><dfn attr-value for="html-global/hidden"><code data-x="attr-hidden-until-found-keyword">until-found</code></dfn>
+     <td>
+    <tr>
+     <td rowspan=2><span data-x="attr-hidden-hidden-state">Hidden state</span>
+     <td>The empty string
+    <tr>
+     <td><dfn attr-value for="html-global/hidden"><code data-x="attr-hidden-hidden-keyword">hidden</code></dfn>
+  </table>
+
+  <p>The attribute may be omitted. The <i data-x="invalid value default">invalid value default</i>
+  is the <span data-x="attr-hidden-hidden-state">hidden state</span>. The <i data-x="missing value
+  default">missing value default</i> is the <dfn data-x="attr-hidden-not-hidden-state">not
+  hidden state</dfn>.</p>
+
+  <p>When an element has the <code data-x="attr-hidden">hidden</code> attribute in the <dfn
+  data-x="attr-hidden-hidden-state">hidden state</dfn>, it indicates that the element is not yet, or
+  is no longer, directly relevant to the page's current state, or that it is being used to declare
+  content to be reused by other parts of the page as opposed to being directly accessed by the user.
+  User agents should not render elements that are in the <span
+  data-x="attr-hidden-hidden-state">hidden state</span>. This requirement may be implemented
+  indirectly through the style layer. For example, a web browser could implement these requirements
+  <a href="#hiddenCSS">using the rules suggested in the Rendering section</a>.</p>
+
+  <p>When an element has the <code data-x="attr-hidden">hidden</code> attribute in the <dfn
+  data-x="attr-hidden-until-found-state">hidden until found state</dfn>, it indicates that the
+  element is hidden like the <span data-x="attr-hidden-hidden-state">hidden state</span> but the
+  content inside the element will be accessible to <span>find-in-page</span> and <span
+  data-x="navigate-fragid">fragment navigation</span>. When these features attempt to scroll to a
+  target which is in the element's subtree, the user agent will remove the <code
+  data-x="attr-hidden">hidden</code> attribute in order to reveal the content before scrolling to
+  it. In addition to removing the <code data-x="attr-hidden">hidden</code> attribute, an event named
+  <code data-x="event-beforematch">beforematch</code> is also fired on the element before the <code
+  data-x="attr-hidden">hidden</code> attribute is removed.</p>
+
+  <p>Web browsers will use 'content-visibility: hidden' instead of 'display: none' when the <code
+  data-x="attr-hidden">hidden</code> attribute is in the <span
+  data-x="attr-hidden-until-found-state">hidden until found state</span>, as specified in the <a
+  href="#hiddenCSS">Rendering section</a>.</p>
+
+
+  <div class="note">
+   <p>Because this attribute is typically implemented using CSS, it's also possible to override it
+   using CSS. For instance, a rule that applies 'display: block' to all elements will cancel the
+   effects of the <span data-x="attr-hidden-hidden-state">hidden</span> state. Authors therefore
+   have to take care when writing their style sheets to make sure that the attribute is still styled
+   as expected. In addition, legacy user agents which don't support the <span
+   data-x="attr-hidden-until-found-state">hidden until found state</span> will have 'display: none'
+   instead of 'content-visibility: hidden', so authors are encouraged to make sure that their style
+   sheets don't change the 'display' or 'content-visibility' properties of <span
+   data-x="attr-hidden-until-found-state">hidden until found</span> elements.</p>
+
+   <p>Since elements with the <code data-x="attr-hidden">hidden</code> attribute in the <span
+   data-x="attr-hidden-until-found-state">hidden until found state</span> use 'content-visibility:
+   hidden' instead of 'display: none', there are two caveats of the <span
+   data-x="attr-hidden-until-found-state">hidden until found state</span> that make it different
+   from the <span data-x="attr-hidden-hidden-state">hidden state</span>:</p>
+
+   <ol>
+    <li><p>The element needs to be affected by <span>layout containment</span> in order to be
+    revealed by find-in-page. This means that if the element in the <span
+    data-x="attr-hidden-until-found-state">hidden until found state</span> has a 'display' value of
+    'none', 'contents', or 'inline', then the element will not be revealed by find-in-page.</p></li>
+
+    <li><p>The element will still have a <span data-x="'visibility'">generated box</span> when in
+    the <span data-x="attr-hidden-until-found-state">hidden until found state</span>, which means
+    that borders, margin, and padding will still be rendered around the element.</p></li>
+   </ol>
+  </div>
 
   <div class="example">
 
@@ -75098,8 +75166,73 @@ END:VCARD</pre>
 
   <div w-nodev>
 
-  <p>The <dfn attribute for="HTMLElement"><code data-x="dom-hidden">hidden</code></dfn> IDL
-  attribute must <span>reflect</span> the content attribute of the same name.</p>
+  <p>The <dfn attribute for="HTMLElement"><code data-x="dom-hidden">hidden</code></dfn> getter steps
+  are:</p>
+
+  <ol>
+   <li><p>If the <code data-x="attr-hidden">hidden</code> attribute is in the <span
+   data-x="attr-hidden-until-found-state">until-found</span> state, then return "<code
+   data-x="attr-hidden-until-found-keyword">until-found</code>".</p></li>
+
+   <li><p>If the <code data-x="attr-hidden">hidden</code> attribute is set, then return
+   true.</p></li>
+
+   <li><p>Return false.</p></li>
+  </ol>
+
+  <p>The <code data-x="dom-hidden">hidden</code> setter steps are:</p>
+
+  <ol>
+   <li><p>If the given value is a string that is an <span>ASCII case-insensitive</span> match for
+   "<code data-x="attr-hidden-until-found-keyword">until-found</code>", then set the <code
+   data-x="attr-hidden">hidden</code> attribute to "<code
+   data-x="attr-hidden-until-found-keyword">until-found</code>".</p></li>
+
+   <li><p>Otherwise, if the given value is false, then remove the <code
+   data-x="attr-hidden">hidden</code> attribute.</p></li>
+
+   <li><p>Otherwise, if the given value is the empty string, then remove the <code
+   data-x="attr-hidden">hidden</code> attribute.</p></li>
+
+   <li><p>Otherwise, if the given value is null, then remove the <code
+   data-x="attr-hidden">hidden</code> attribute.</p></li>
+
+   <li><p>Otherwise, if the given value is 0, then remove the <code
+   data-x="attr-hidden">hidden</code> attribute.</p></li>
+
+   <li><p>Otherwise, if the given value is NaN, then remove the <code
+   data-x="attr-hidden">hidden</code> attribute.</p></li>
+
+   <li><p>Otherwise, set the <code data-x="attr-hidden">hidden</code> attribute to the empty
+   string.</p></li>
+  </ol>
+
+  <p>The <dfn>ancestor hidden-until-found revealing algorithm</dfn> is to run the following steps on
+  <var>currentNode</var>:</p>
+
+  <ol>
+   <li>
+    <p>While <var>currentNode</var> has a parent node within the <span>flat tree</span>:</p>
+
+    <ol>
+     <li>
+      <p>If <var>currentNode</var> has the <code data-x="attr-hidden">hidden</code> attribute in the
+      <span data-x="attr-hidden-until-found-state">hidden until found</span> state, then:</p>
+
+      <ol>
+       <li><p><span data-x="concept-event-fire">Fire an event</span> named <code
+       data-x="event-beforematch">beforematch</code> at <var>currentNode</var>.</p></li>
+
+       <li><p>Remove the <code data-x="attr-hidden">hidden</code> attribute from
+       <var>currentNode</var>.</p></li>
+      </ol>
+     </li>
+
+     <li><p>Set <var>currentNode</var> to the parent node of <var>currentNode</var> within the
+     <span>flat tree</span>.</p></li>
+    </ol>
+   </li>
+  </ol>
 
   </div>
 
@@ -78121,16 +78254,23 @@ body { display:none }
   standardizing how <span>find-in-page</span> underlies the currently-unspecified <code
   data-x="">window.find()</code> API.</p>
 
-  <h4>Interaction with <code>details</code></h4>
+  <h4>Interaction with <code>details</code> and <code
+  data-x="attr-hidden-until-found-state">hidden=until-found</code></h4>
 
   <p>When find-in-page begins searching for matches, all <code>details</code> elements in the page
-  which do not have their <code data-x="attr-details-open">open</code> attribute set should have
-  the <span data-x="skips its contents">skipped contents</span> of their second slot become
-  accessible, without modifying the <code data-x="attr-details-open">open</code> attribute, in
-  order to make find-in-page able to search through it. After find-in-page finishes searching for
-  matches, those <code>details</code> elements should have their contents become skipped again.
-  This entire process must happen synchronously (and so is not observable to users or to author
-  code). <ref spec=CSSCONTAIN></p>
+  which do not have their <code data-x="attr-details-open">open</code> attribute set should have the
+  <span data-x="skips its contents">skipped contents</span> of their second slot become accessible,
+  without modifying the <code data-x="attr-details-open">open</code> attribute, in order to make
+  find-in-page able to search through it. Similarly, all HTML elements with the <code
+  data-x="attr-hidden">hidden</code> attribute in the <span
+  data-x="attr-hidden-until-found-state">hidden until found state</span> should have their <span
+  data-x="skips its contents">skipped contents</span> become accessible without modifying the <code
+  data-x="attr-hidden">hidden</code> attribute in order to make find-in-page able to search through
+  them. After find-in-page finishes searching for matches, the <code>details</code> elements and the
+  elements with the <code data-x="attr-hidden">hidden</code> attribute in the <span
+  data-x="attr-hidden-until-found-state">hidden until found state</span> should have their contents
+  become skipped again. This entire process must happen synchronously (and so is not observable to
+  users or to author code). <ref spec=CSSCONTAIN></p>
 
   <p>When find-in-page chooses a new <span data-x="fip-active-match">active match</span>, perform
   the following steps:</p>
@@ -78140,8 +78280,15 @@ body { display:none }
    match</span>.</p></li>
 
    <li><p><span>Queue a global task</span> on the <span>user interaction task source</span> given
-   <var>node</var>'s <span>relevant global object</span> to run the <span>ancestor details
-   revealing algorithm</span> on <var>node</var>.</p></li>
+   <var>node</var>'s <span>relevant global object</span> to run the following steps:</p>
+
+    <ol>
+     <li><p>Run the <span>ancestor details revealing algorithm</span> on <var>node</var>.</p></li>
+
+     <li><p>Run the <span>ancestor hidden-until-found revealing algorithm</span> on
+     <var>node</var>.</p></li>
+    </ol>
+   </li>
   </ol>
 
   <p class="warning">
@@ -89629,6 +89776,9 @@ new PaymentRequest(&hellip;); // Allowed to use
 
      <li><p>Run the <span>ancestor details revealing algorithm</span> on <var>target</var>.</p></li>
 
+     <li><p>Run the <span>ancestor hidden-until-found revealing algorithm</span> on
+     <var>target</var>.</p></li>
+
      <li><p><span data-x="scroll an element into view">Scroll <var>target</var> into view</span>,
      with <var>behavior</var> set to "auto", <var>block</var> set to "start", and <var>inline</var>
      set to "nearest". <ref spec=CSSOMVIEW></p></li>
@@ -96510,6 +96660,7 @@ typedef <span>OnBeforeUnloadEventHandlerNonNull</span>? <dfn typedef>OnBeforeUnl
    <tbody>
     <tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onabort">onabort</code></dfn> <td> <code data-x="">abort</code>
     <tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onauxclick">onauxclick</code></dfn> <td> <code data-x="event-auxclick">auxclick</code>
+    <tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-onbeforematch">onbeforematch</code></dfn> <td> <code data-x="event-beforematch">beforematch</code>
     <tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oncancel">oncancel</code></dfn> <td> <code data-x="event-cancel">cancel</code>
     <tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oncanplay">oncanplay</code></dfn> <td> <code data-x="event-media-canplay">canplay</code>
     <tr><td><dfn attribute for="HTMLElement,Document,Window,GlobalEventHandlers"><code data-x="handler-oncanplaythrough">oncanplaythrough</code></dfn> <td> <code data-x="event-media-canplaythrough">canplaythrough</code>
@@ -96694,6 +96845,7 @@ typedef <span>OnBeforeUnloadEventHandlerNonNull</span>? <dfn typedef>OnBeforeUnl
   <pre><code class="idl">interface mixin <dfn interface>GlobalEventHandlers</dfn> {
   attribute <span>EventHandler</span> <span data-x="handler-onabort">onabort</span>;
   attribute <span>EventHandler</span> <span data-x="handler-onauxclick">onauxclick</span>;
+  attribute <span>EventHandler</span> <span data-x="handler-onbeforematch">onbeforematch</span>;
   attribute <span>EventHandler</span> <span data-x="handler-onblur">onblur</span>;
   attribute <span>EventHandler</span> <span data-x="handler-oncancel">oncancel</span>;
   attribute <span>EventHandler</span> <span data-x="handler-oncanplay">oncanplay</span>;
@@ -116731,11 +116883,19 @@ console.assert(container.firstChild instanceof SuperP);
 
   <pre><code class="css">@namespace url(http://www.w3.org/1999/xhtml);
 
-<span id="hiddenCSS" data-x="">[hidden]</span>, area, base, basefont, datalist, head, link, meta, noembed,
+area, base, basefont, datalist, head, link, meta, noembed,
 noframes, param, rp, script, style, template, title {
   display: none;
 }
 
+<span id="hiddenCSS" data-x="">[hidden]:not([hidden=until-found i])</span> {
+  display: none;
+}
+
+[hidden=until-found i]:not(embed) {
+  content-visibility: hidden;
+}
+
 embed[hidden] { display: inline; height: 0; width: 0; } <!-- because for legacy reasons it still needs to instantiate the plugin -->
 
 input[type=hidden i] { display: none !important; }
@@ -124899,6 +125059,12 @@ interface <dfn interface>External</dfn> {
      <td> <code data-x="event-afterprint">afterprint</code> event handler for <code>Window</code> object
      <td> <span data-x="event handler content attributes">Event handler content attribute</span>
 
+    <tr>
+     <th id="ix-handler-onbeforematch"> <code data-x="">onbeforematch</code>
+     <td> <span data-x="handler-onbeforematch">HTML elements</span>
+     <td> <code data-x="event-beforematch">beforematch</code> event handler
+     <td> <span data-x="event handler content attributes">Event handler content attribute</span>
+
     <tr>
      <th id="ix-handler-window-onbeforeprint"> <code data-x="">onbeforeprint</code>
      <td> <code data-x="handler-window-onbeforeprint">body</code>
@@ -125887,6 +126053,14 @@ INSERT INTERFACES HERE
      <td> <code>Window</code>
      <td> Fired at the <code>Window</code> before printing
 
+    <tr> <!-- beforematch -->
+     <td> <dfn event for="HTMLElement"><code data-x="event-beforematch">beforematch</code></dfn>
+     <td> <code>Event</code>
+     <td> Elements
+     <td> Fired on elements with the <code
+     data-x="attr-hidden-until-found-state">hidden=until-found</code> attribute before they are
+     revealed.
+
     <tr> <!-- beforeunload -->
      <td> <dfn event for="Window"><code data-x="event-beforeunload">beforeunload</code></dfn>
      <td> <code>BeforeUnloadEvent</code>