From 4acb3c67790e87fb1b048cdc9eab50180d4ff14b Mon Sep 17 00:00:00 2001 From: Noam Rosenthal Date: Mon, 18 Oct 2021 18:23:00 +0300 Subject: [PATCH] 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 3285b988b8e962d9692e547fd3101ceb23cb1cb6 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 https://github.com/w3c/page-visibility/issues/74 and https://github.com/w3c/page-visibility/pull/73 for more background. --- source | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 76 insertions(+), 10 deletions(-) diff --git a/source b/source index 06cd7e415c2..aaefc9551b6 100644 --- a/source +++ b/source @@ -9274,6 +9274,7 @@ o.myself = o; this specification extends significantly.

enum DocumentReadyState { "loading", "interactive", "complete" };
+enum DocumentVisibilityState { "visible", "hidden" };
 typedef (HTMLScriptElement or SVGScriptElement) HTMLOrSVGScriptElement;
 
 [LegacyOverrideBuiltIns]
@@ -9318,6 +9319,8 @@ partial interface Document {
   boolean queryCommandState(DOMString commandId);
   boolean queryCommandSupported(DOMString commandId);
   DOMString queryCommandValue(DOMString commandId);
+  readonly attribute boolean hidden;
+  readonly attribute DocumentVisibilityState visibilityState;
 
   // special event handler IDL attributes that only apply to Document objects
   [LegacyLenientThis] attribute EventHandler onreadystatechange;
@@ -74108,6 +74111,61 @@ END:VCARD
+

Page visibility

+ +

A top-level browsing context has a system visibility state, + which is either "hidden" or "visible".

+ +

The system visibility state 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.

+ +

When a user-agent determines that the system visibility state for + top-level browsing context context has changed to newState, + it must queue a task on the user interaction task source to + update the visibility state of all the Document objects in the + top-level browsing context's document family with + newState.

+ +

A Document has a visibility state, which is either + "hidden" or "visible", initially set to + "hidden".

+ +

The visibilityState getter steps are to return + this's visibility state.

+ +

The hidden getter + steps are to return true if this's visibility state is + "hidden", otherwise false.

+ +

To update the visibility state of Document document to + visibilityState:

+ +
    +

  1. If document's visibility state equals visibilityState, + then return.

    2. + +

  2. Set document's visibility state to + visibilityState.

    3. + +
  3. +

    Run any page visibility change steps which may be defined in other + specificactions, with visibility state and document.

    + +

    It would be better if specification authors sent a pull request to add calls + from here into their specifications directly, instead of using the page visibility change + steps hook, to ensure well-defined cross-specification call order. As of the time of + this writing the following specifications are known to have page visibility change + steps, which will be run in an unspecified order: Device Posture API, + Screen Orientation API, and Web NFC.

    +
    4. + +

  4. Fire an event named visibilitychange at + document, with its bubbles attribute + initialized to true.

    5. +

Inert subtrees

@@ -79241,6 +79299,9 @@ popup4.close();

  • Let window be document's relevant global object.

    • +

  • Set document's visibility state to browsingContext's + top-level browsing context's system visibility state.

    • +

  • Set browsingContext's active window to window.

  • Set window's associated @@ -79369,8 +79430,8 @@ popup4.close(); data-x="concept-document-permissions-policy">permissions policy is permissionsPolicy, cross-origin opener policy is coop, - navigation id is null, - and which is ready for post-load tasks.

    • + navigation id is null, and which is + ready for post-load tasks.

  • Assert: document's URL and document's relevant settings object's

    Set newDocument's page showing flag to true.

    • -

  • Fire an event named visibilitychange at - newDocument, with its bubbles attribute - initialized to true.

    • +

  • Update the visibility state of newDocument to + "hidden".

  • Fire a page transition event named pageshow at newDocument's relevant global @@ -89106,9 +89166,8 @@ dictionary PageTransitionEventInit : EventInit with document's salvageable state.

    • -

  • Fire an event named visibilitychange at - newDocument, with its bubbles attribute - initialized to true.

    • +

  • Update the visibility state of newDocument to + "hidden".

    • @@ -93640,8 +93699,9 @@ import "https://example.com/foo/../module2.mjs";

    Browsing context rendering opportunities 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.

    + rates and other factors such as page performance or whether the document's + visibility state is "visible". Rendering opportunities + typically occur at regular intervals.

    This specification does not mandate any particular model for selecting rendering opportunities. But for example, if the browser is attempting to achieve a 60Hz @@ -126095,6 +126155,9 @@ INSERT INTERFACES HERE

    [DASH]
    Dynamic adaptive streaming over HTTP (DASH). ISO.
    +
    [DEVICEPOSTURE]
    +
    (Non-normative) Device Posture API, D. Gonzalez-Zuniga, K. Christiansen. W3C.
    +
    [DOM]
    DOM, A. van Kesteren, A. Gregor, Ms2ger. WHATWG.
    @@ -126488,6 +126551,9 @@ INSERT INTERFACES HERE
    [WEBMCG]
    WebM Container Guidelines. The WebM Project.
    +
    [WEBNFC]
    +
    (Non-normative) Web NFC, F. Beaufort, K. Christiansen, Z. Kis. W3C.
    +
    [WEBVTT]
    WebVTT, S. Pieters. W3C.