Move Page Visibility APIs into HTML

Defines the document.hidden and document.visibilityState APIs in the HTML Standard, while improving their definitions to be more rigorous. This is similar to 3285b98 which did the same for the visibilitychange event.

Also updates the discussion of "page is in the background" to refer to the new definitions.

See w3c/page-visibility#74 and w3c/page-visibility#73 for more background.

Author: noamr

source

@@ -9276,6 +9276,7 @@ o.myself = o;</code></pre>
   this specification extends significantly.</p>
 
   <pre><code class="idl">enum <dfn enum>DocumentReadyState</dfn> { "loading", "interactive", "complete" };
+enum <dfn enum>DocumentVisibilityState</dfn> { "visible", "hidden" };
 typedef (<span>HTMLScriptElement</span> or <span>SVGScriptElement</span>) <dfn typedef>HTMLOrSVGScriptElement</dfn>;
 
 [<span>LegacyOverrideBuiltIns</span>]
@@ -9320,6 +9321,8 @@ partial interface <dfn id="document" data-lt="">Document</dfn> {
   boolean <span data-x="dom-document-queryCommandState">queryCommandState</span>(DOMString commandId);
   boolean <span data-x="dom-document-queryCommandSupported">queryCommandSupported</span>(DOMString commandId);
   DOMString <span data-x="dom-document-queryCommandValue">queryCommandValue</span>(DOMString commandId);
+  readonly attribute boolean <span data-x="dom-document-hidden">hidden</span>;
+  readonly attribute <span>DocumentVisibilityState</span> <span data-x="dom-document-visibilityState">visibilityState</span>;
 
   // special <span>event handler IDL attributes</span> that only apply to Document objects
   [<span>LegacyLenientThis</span>] attribute <span>EventHandler</span> <span data-x="handler-onreadystatechange">onreadystatechange</span>;
@@ -74111,6 +74114,61 @@ END:VCARD</pre>
 
   </div>
 
+  <h3>Page visibility</h3>
+
+  <p>A <span>top-level browsing context</span> has a <dfn>system visibility state</dfn>,
+  which is either "<code data-x="">hidden</code>" or "<code data-x="">visible</code>".</p>
+
+  <p class="note">The <span>system visibility state</span> is determined by the user-agent, and
+  represents, for example, whether the browser window is minimized, a browser tab is currently in
+  the background, or a system element such as a task switcher obscures the page.</p>
+
+  <p>When a user-agent determines that the <span>system visibility state</span> for
+  <span>top-level browsing context</span> <var>context</var> has changed to <var>newState</var>,
+  it must <span>queue a task</span> on the <span>user interaction task source</span> to
+  <span>update the visibility state</span> of all the <code>Document</code> objects in the
+  <span>top-level browsing context</span>'s <span>document family</span> with
+  <var>newState</var>.</p>
+
+  <p>A <code>Document</code> has a <dfn>visibility state</dfn>, which is either
+  "<code data-x="">hidden</code>" or "<code data-x="">visible</code>", initially set to
+  "<code data-x="">hidden</code>".</p>
+
+  <p>The <dfn attribute for="Document"><code
+  data-x="dom-document-visibilityState">visibilityState</code></dfn> getter steps are to return
+  <span>this</span>'s <span>visibility state</span>.</p>
+
+  <p>The <dfn attribute for="Document"><code data-x="dom-document-hidden">hidden</code></dfn> getter
+  steps are to return true if <span>this</span>'s <span>visibility state</span> is
+  "<code data-x="">hidden</code>", otherwise false.</p>
+
+  <p>To <dfn>update the visibility state</dfn> of <code>Document</code> <var>document</var> to
+  <var>visibilityState</var>:</p>
+
+  <ol>
+   <li><p>If <var>document</var>'s <span>visibility state</span> equals <var>visibilityState</var>,
+   then return.</p></li>
+
+   <li><p>Set <var>document</var>'s <span>visibility state</span> to
+   <var>visibilityState</var>.</p></li>
+
+   <li>
+    <p>Run any <dfn export>page visibility change steps</dfn> which may be defined in other
+    specificactions, with <span>visibility state</span> and <var>document</var>.</p>
+
+    <p class="XXX">It would be better if specification authors sent a pull request to add calls
+    from here into their specifications directly, instead of using the <span>page visibility change
+    steps</span> hook, to ensure well-defined cross-specification call order. As of the time of
+    this writing the following specifications are known to have <span>page visibility change
+    steps</span>, which will be run in an unspecified order: <cite>Device Posture API</cite>,
+    <cite>Screen Orientation API</cite>, and <cite>Web NFC</cite>. <ref spec=DEVICEPOSTURE> <ref
+    spec=SCREENORIENTATION> <ref spec=WEBNFC></p>
+   </li>
+
+   <li><p>Fire an event named <code data-x="event-visibilitychange">visibilitychange</code> at
+   <var>document</var>, with its <code data-x="dom-Event-bubbles">bubbles</code> attribute
+   initialized to true.</p></li>
+  </ol>
 
 
   <h3>Inert subtrees</h3>
@@ -79244,6 +79302,9 @@ popup4.close();</code></pre></div>
    <li><p>Let <var>window</var> be <var>document</var>'s <span>relevant global
    object</span>.</p></li>
 
+   <li><p>Set <var>document</var>'s <span>visibility state</span> to <var>browsingContext</var>'s
+   <span>top-level browsing context</span>'s <span>system visibility state</span>.</p></li>
+
    <li><p>Set <var>browsingContext</var>'s <span>active window</span> to <var>window</var>.</p></li>
 
    <li><p>Set <var>window</var>'s <span data-x="concept-document-window">associated
@@ -79372,8 +79433,8 @@ popup4.close();</code></pre></div>
    data-x="concept-document-permissions-policy">permissions policy</span> is
    <var>permissionsPolicy</var>, <span data-x="concept-document-coop">cross-origin opener
    policy</span> is <var>coop</var>,
-   <span data-x="concept-document-navigation-id">navigation id</span> is null,
-   and which is <span>ready for post-load tasks</span>.</p></li>
+   <span data-x="concept-document-navigation-id">navigation id</span> is null, and which is
+   <span>ready for post-load tasks</span>.</p></li>
 
    <li><p>Assert: <var>document</var>'s <span data-x="concept-document-url">URL</span> and
    <var>document</var>'s <span>relevant settings object</span>'s <span
@@ -88638,9 +88699,8 @@ new PaymentRequest(&hellip;); // Allowed to use
 
        <li><p>Set <var>newDocument</var>'s <span>page showing</span> flag to true.</p></li>
 
-       <li><p>Fire an event named <code data-x="event-visibilitychange">visibilitychange</code> at
-       <var>newDocument</var>, with its <code data-x="dom-Event-bubbles">bubbles</code> attribute
-       initialized to true.</p></li>
+       <li><p><span>Update the visibility state</span> of <var>newDocument</var> to
+       "<code data-x="">hidden</code>".</p></li>
 
        <li><p><span>Fire a page transition event</span> named <code
        data-x="event-pageshow">pageshow</code> at <var>newDocument</var>'s <span>relevant global
@@ -89109,9 +89169,8 @@ dictionary <dfn dictionary>PageTransitionEventInit</dfn> : <span>EventInit</span
      object</span> with <var>document</var>'s <i
      data-x="concept-document-salvageable">salvageable</i> state.</p></li>
 
-     <li><p>Fire an event named <code data-x="event-visibilitychange">visibilitychange</code> at
-     <var>newDocument</var>, with its <code data-x="dom-Event-bubbles">bubbles</code> attribute
-     initialized to true.</p></li>
+     <li><p><span>Update the visibility state</span> of <var>newDocument</var> to
+     "<code data-x="">hidden</code>".</p></li>
     </ol>
   </li>
 
@@ -93643,8 +93702,9 @@ import "https://example.com/foo/../module2.mjs";</code></pre>
 
       <p><span>Browsing context</span> <span data-x="rendering opportunity">rendering
       opportunities</span> are determined based on hardware constraints such as display refresh
-      rates and other factors such as page performance or whether the page is in the background.
-      Rendering opportunities typically occur at regular intervals.</p>
+      rates and other factors such as page performance or whether the document's
+      <span>visibility state</span> is "<code data-x="">visible</code>". Rendering opportunities
+      typically occur at regular intervals.</p>
 
       <p class="note">This specification does not mandate any particular model for selecting
       rendering opportunities. But for example, if the browser is attempting to achieve a 60Hz
@@ -126106,6 +126166,9 @@ INSERT INTERFACES HERE
    <dt id="refsDASH">[DASH]</dt>
    <dd><cite><a href="https://www.iso.org/standard/65274.html">Dynamic adaptive streaming over HTTP (DASH)</a></cite>. ISO.</dd>
 
+   <dt id="refsDEVICEPOSTURE">[DEVICEPOSTURE]</dt>
+   <dd>(Non-normative) <cite><a href="https://w3c.github.io/device-posture/">Device Posture API</a></cite>, D. Gonzalez-Zuniga, K. Christiansen. W3C.</dd>
+
    <dt id="refsDOM">[DOM]</dt>
    <dd><cite><a href="https://dom.spec.whatwg.org/">DOM</a></cite>, A. van Kesteren, A. Gregor, Ms2ger. WHATWG.</dd>
 
@@ -126499,6 +126562,9 @@ INSERT INTERFACES HERE
    <dt id="refsWEBMCG">[WEBMCG]</dt>
    <dd><cite><a href="https://www.webmproject.org/docs/container/">WebM Container Guidelines</a></cite>. The WebM Project.</dd>
 
+   <dt id="refsWEBNFC">[WEBNFC]</dt>
+   <dd>(Non-normative) <cite><a href="https://w3c.github.io/web-nfc/">Web NFC</a></cite>, F. Beaufort, K. Christiansen, Z. Kis. W3C.</dd>
+
    <dt id="refsWEBVTT">[WEBVTT]</dt>
    <dd><cite><a href="https://w3c.github.io/webvtt/">WebVTT</a></cite>, S. Pieters. W3C.</dd>