Skip to content

Commit

Permalink
Move Page Visibility APIs into HTML
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@domenic
Noam Rosenthal authored and domenic committed Nov 3, 2021
1 parent 6b24119 commit 4acb3c6
Showing 1 changed file with 76 additions and 10 deletions.
86 changes: 76 additions & 10 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9274,6 +9274,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>]
Expand Down Expand Up @@ -9318,6 +9319,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>;
Expand Down Expand Up @@ -74108,6 +74111,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>
Expand Down Expand Up @@ -79241,6 +79299,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
Expand Down Expand Up @@ -79369,8 +79430,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
Expand Down Expand Up @@ -88635,9 +88696,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
Expand Down Expand Up @@ -89106,9 +89166,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>

Expand Down Expand Up @@ -93640,8 +93699,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
Expand Down Expand Up @@ -126095,6 +126155,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>

Expand Down Expand Up @@ -126488,6 +126551,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>

Expand Down

0 comments on commit 4acb3c6

Please sign in to comment.