From 14ab07a19a0416239354745df9815535e279cfda Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Mon, 15 Jul 2024 13:19:21 +0200 Subject: [PATCH] Review Draft Publication: July 2024 --- fullscreen.bs | 2 +- review-drafts/2024-07.bs | 742 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 743 insertions(+), 1 deletion(-) create mode 100644 review-drafts/2024-07.bs diff --git a/fullscreen.bs b/fullscreen.bs index ce9ed9f..f5a1e20 100644 --- a/fullscreen.bs +++ b/fullscreen.bs @@ -3,7 +3,7 @@ Group: WHATWG H1: Fullscreen API Shortname: fullscreen Text Macro: TWITTER fullscreenapi -Text Macro: LATESTRD 2023-07 +Text Macro: LATESTRD 2024-07 Abstract: The Fullscreen API standard defines an API for elements to display themselves fullscreen. Translation: ja https://triple-underscore.github.io/fullscreen-ja.html Markup Shorthands: css no diff --git a/review-drafts/2024-07.bs b/review-drafts/2024-07.bs new file mode 100644 index 0000000..ab3f50d --- /dev/null +++ b/review-drafts/2024-07.bs @@ -0,0 +1,742 @@ +
+Group: WHATWG
+Status: RD
+Date: 2024-07-15
+H1: Fullscreen API
+Shortname: fullscreen
+Text Macro: TWITTER fullscreenapi
+Text Macro: LATESTRD 2024-07
+Abstract: The Fullscreen API standard defines an API for elements to display themselves fullscreen.
+Translation: ja https://triple-underscore.github.io/fullscreen-ja.html
+Markup Shorthands: css no
+
+ +
+spec:dom
+    type:dfn; for:/; text:element
+    type:interface; text:Document
+spec:infra
+    type:dfn; for:set; text:for each
+    type:dfn; text:string
+spec:css-position-4
+    type:selector; text: ::backdrop
+    type:dfn; text:top layer
+
+ +
+urlPrefix: https://w3c.github.io/screen-orientation/#dfn-
+    type: dfn
+        text: triggered by a user generated orientation change
+
+ +
+{
+    "CSS": {
+        "aliasOf": "CSS2"
+    },
+    "SVG": {
+        "aliasOf": "SVG11"
+    }
+}
+
+ + + +

Terminology

+ +

This specification depends on the Infra Standard. [[!INFRA]] + +

Most terminology used in this specification is from CSS, DOM, HTML, and Web IDL. [[!CSS]] +[[!DOM]] [[!HTML]] [[!WEBIDL]] + + + +

Model

+ +

All elements have an associated fullscreen flag. Unless stated otherwise it is +unset. + +

All <{iframe}> elements have an associated iframe fullscreen flag. Unless +stated otherwise it is unset. + +

All documents have an associated fullscreen element. The +fullscreen element is the topmost element in the document's +top layer whose fullscreen flag is set, if any, and null otherwise. + +

All documents have an associated list of pending fullscreen events, which +is an ordered set of (string, element) tuples. It is initially empty. + +

To fullscreen an element: + +

    +

  1. Let hideUntil be the result of running topmost popover ancestor given + element, null, and false. + +

  2. If hideUntil is null, then set hideUntil to element's + node document. + +

  3. Run hide all popovers until given hideUntil, false, and true. + +

  4. Set element's fullscreen flag. + +

  5. Remove from the top layer immediately given element. + +

  6. Add to the top layer given element. +
+ +

To unfullscreen an element, unset element's +fullscreen flag and iframe fullscreen flag (if any), and +remove from the top layer immediately given element. + +

To unfullscreen a document, +unfullscreen all elements, within document's +top layer, whose fullscreen flag is set. + +

+ +
+

To fully exit fullscreen a document document, run these steps: + +

    +

  1. If document's fullscreen element is null, terminate these steps. + +

  2. Unfullscreen elements whose fullscreen flag is + set, within document's top layer, except for document's + fullscreen element. + +

  3. Exit fullscreen document. +

+
+ +
+

Whenever the removing steps run with a removedNode, run +these steps: + +

    +

  1. Let document be removedNode's node document. + +

  2. Let nodes be removedNode's + shadow-including inclusive descendants that have their fullscreen flag set, in + shadow-including tree order. + +

  3. +

    For each node in nodes: + +

      +

    1. If node is document's fullscreen element, + exit fullscreen document. + +

    2. Otherwise, unfullscreen node. + +

    3. +

      If document's top layer contains node, + remove from the top layer immediately given node. + +

      Other specifications can add and remove elements from top layer, so + node might not be document's fullscreen element. For example, + node could be an open <{dialog}> element. +

    +
+
+ +

Whenever the unloading document cleanup steps run with a document, +fully exit fullscreen document. + +

+ +

Fullscreen is supported if there is no previously-established user preference, +security risk, or platform limitation. + +

+ +
+

To run the fullscreen steps for a document document, run these +steps: + +

    +

  1. Let pendingEvents be document's + list of pending fullscreen events. + +

  2. Empty document's list of pending fullscreen events. + +

  3. +

    For each (type, element) in pendingEvents: + +

      +

    1. Let target be element if element is connected + and its node document is document, and otherwise let target be + document. + +

    2. Fire an event named type, with its {{Event/bubbles}} and + {{Event/composed}} attributes set to true, at target. +

    +
+ +

These steps integrate with the event loop defined in HTML. [[!HTML]] +

+ + + +

API

+ +
+enum FullscreenNavigationUI {
+  "auto",
+  "show",
+  "hide"
+};
+
+dictionary FullscreenOptions {
+  FullscreenNavigationUI navigationUI = "auto";
+};
+
+partial interface Element {
+  Promise<undefined> requestFullscreen(optional FullscreenOptions options = {});
+
+  attribute EventHandler onfullscreenchange;
+  attribute EventHandler onfullscreenerror;
+};
+
+partial interface Document {
+  [LegacyLenientSetter] readonly attribute boolean fullscreenEnabled;
+  [LegacyLenientSetter, Unscopable] readonly attribute boolean fullscreen; // historical
+
+  Promise<undefined> exitFullscreen();
+
+  attribute EventHandler onfullscreenchange;
+  attribute EventHandler onfullscreenerror;
+};
+
+partial interface mixin DocumentOrShadowRoot {
+  [LegacyLenientSetter] readonly attribute Element? fullscreenElement;
+};
+
+ + +
+
promise = element . requestFullscreen([options]) +
+ Displays element fullscreen and resolves promise when done. + + When supplied, options's {{FullscreenOptions/navigationUI}} member indicates whether + showing navigation UI while in fullscreen is preferred or not. If set to + "{{FullscreenNavigationUI/show}}", navigation simplicity is preferred over screen space, and if + set to "{{FullscreenNavigationUI/hide}}", more screen space is preferred. User agents are always + free to honor user preference over the application's. The default value + "{{FullscreenNavigationUI/auto}}" indicates no application preference. + +
document . {{Document/fullscreenEnabled}} +

Returns true if document has the ability to display elements fullscreen + and fullscreen is supported, or false otherwise. + +

promise = document . {{Document/exitFullscreen()}} +

Stops document's fullscreen element from being displayed fullscreen and + resolves promise when done. + +

document . {{DocumentOrShadowRoot/fullscreenElement}} +

Returns document's fullscreen element. + +

shadowroot . {{DocumentOrShadowRoot/fullscreenElement}} +

Returns shadowroot's fullscreen element. +

+ +

A fullscreen element ready check for an element element returns true +if all of the following are true, and false otherwise: + +

+ +
+

The requestFullscreen(options) method steps +are: + +

    +

  1. Let pendingDoc be this's node document. + +

  2. Let promise be a new promise. + +

  3. If pendingDoc is not fully active, then reject promise with a + {{TypeError}} exception and return promise. + +

  4. Let error be false. + +

  5. +

    If any of the following conditions are false, then set error to true: + +

    + +

  6. If error is false, then consume user activation given + pendingDoc's relevant global object. + +

  7. Return promise, and run the remaining steps in parallel. + +

  8. +

    If error is false, then resize pendingDoc's node navigable's + top-level traversable's active document's viewport's + dimensions, optionally taking into account + options["{{FullscreenOptions/navigationUI}}"]: + + + + + + + + + + + + + + + + + + + + + + + +
    valueviewport dimensions
    "hide"full dimensions of the screen of the output device
    "show"dimensions of the screen of the output device clamped to allow the user agent to show page navigation controls
    "auto"user-agent defined, but matching one of the above
    + +

    Optionally display a message how the end user can revert this. + +

  9. +

    If any of the following conditions are false, then set error to true: + +

    + +
  10. +

    If error is true: + +

      +

    1. Append ({{fullscreenerror}}, this) to + pendingDoc's list of pending fullscreen events. + +

    2. Reject promise with a {{TypeError}} exception and terminate these + steps. +

    + +

  11. Let fullscreenElements be an ordered set initially consisting of + this. + +

  12. +

    While true: + +

      +

    1. Let last be the last item of fullscreenElements. + +

    2. Let container be last's node navigable's + container. + +

    3. If container is null, then break. + +

    4. Append container to fullscreenElements. +

    +
    13. + + +
  13. +

    For each element in fullscreenElements: + +

      +

    1. Let doc be element's node document. + +

    2. +

      If element is doc's fullscreen element, continue. + +

      No need to notify observers when nothing has changed. + +

    3. If element is this and this is an <{iframe}> + element, then set element's iframe fullscreen flag. + +

    4. Fullscreen element within doc. + +

    5. Append ({{fullscreenchange}}, element) to + doc's list of pending fullscreen events. +

    + +

    The order in which elements are fullscreened + is not observable, because run the fullscreen steps is invoked in tree order. + +

  14. Resolve promise with undefined. +

+ +

Implementations with out-of-process navigables are left as an exercise +to the reader. Input welcome on potential improvements. +

+ +

The fullscreenEnabled getter steps are to return +true if this is allowed to use the "fullscreen" feature and fullscreen is supported, and +false otherwise. + +

The fullscreen getter steps are to return false if +this's fullscreen element is null, and true otherwise. + +

Use the {{DocumentOrShadowRoot/fullscreenElement}} attribute instead. + +

+

The +fullscreenElement +getter steps are: + +

    +

  1. If this is a shadow root and its host is not + connected, then return null. + +

  2. Let candidate be the result of retargeting fullscreen element + against this. + +

  3. If candidate and this are in the same tree, then return + candidate. + +

  4. Return null. +

+
+ +

A document is said to be a simple fullscreen document if there is exactly one +element in its top layer that has its fullscreen flag set. + +

A document with two elements in its top layer can be a +simple fullscreen document. For example, in addition to the fullscreen element there +could be an open <{dialog}> element. + +

+

To collect documents to unfullscreen given doc, run these steps: + +

    +

  1. Let docs be an ordered set consisting of doc. + +

  2. +

    While true: + +

      +

    1. Let lastDoc be docs's last document. + +

    2. Assert: lastDoc's fullscreen element is not null. + +

    3. If lastDoc is not a simple fullscreen document, break. + +

    4. Let container be lastDoc's node navigable's + container. + +

    5. If container is null, then break. + +

    6. If container's iframe fullscreen flag is set, break. + +

    7. Append container's node document to docs. +

    + +

  3. Return docs. + +

    This is the set of documents for which the fullscreen element will be + unfullscreened, but the last document in docs might + have more than one element in its top layer with the fullscreen flag set, + in which case that document will still remain in fullscreen. +

+
+ +
+

To exit fullscreen a document doc, run these steps: + +

    +

  1. Let promise be a new promise. + +

  2. If doc is not fully active or doc's fullscreen element + is null, then reject promise with a {{TypeError}} exception and return + promise. + +

  3. Let resize be false. + +

  4. Let docs be the result of + collecting documents to unfullscreen given + doc. + + +

  5. Let topLevelDoc be doc's node navigable's + top-level traversable's active document. + + +

  6. If topLevelDoc is in docs, and it is a + simple fullscreen document, then set doc to topLevelDoc and + resize to true. + +

  7. If doc's fullscreen element is not connected: +

      +

    1. Append ({{fullscreenchange}}, doc's + fullscreen element) to doc's + list of pending fullscreen events. +

    + +

  8. Return promise, and run the remaining steps in parallel. + +

  9. Run the [=fully unlock the screen orientation steps=] with doc. + +

  10. If resize is true, resize doc's viewport to its "normal" dimensions. + +

  11. If doc's fullscreen element is null, then resolve promise with + undefined and terminate these steps. + +

  12. Let exitDocs be the result of + collecting documents to unfullscreen given + doc. + + +

  13. Let descendantDocs be an ordered set consisting of doc's + descendant navigables' active documents whose + fullscreen element is non-null, if any, in tree order. + + +

  14. +

    For each exitDoc in exitDocs: + +

      +

    1. Append ({{fullscreenchange}}, exitDoc's + fullscreen element) to exitDoc's list of pending fullscreen events. + +

    2. If resize is true, unfullscreen + exitDoc. + +

    3. Otherwise, unfullscreen exitDoc's + fullscreen element. +

    + +
  15. +

    For each descendantDoc in descendantDocs: + +

      +

    1. Append ({{fullscreenchange}}, descendantDoc's + fullscreen element) to descendantDoc's + list of pending fullscreen events. + +

    2. Unfullscreen descendantDoc. +

    + +

    The order in which documents are unfullscreened + is not observable, because run the fullscreen steps is invoked in tree order. + +

  16. Resolve promise with undefined. +

+
+ +

The exitFullscreen() method steps are to return the +result of running exit fullscreen on this. + +

+ +

The following are the event handlers (and their corresponding +event handler event types) that must be supported by {{Element}} and {{Document}} objects as +event handler IDL attributes: + + + + + + + +
event handler + event handler event type +
onfullscreenchange + fullscreenchange +
onfullscreenerror + fullscreenerror +
+ +

These are not supported by {{ShadowRoot}} or {{Window}} objects, and there are no +corresponding event handler content attributes for {{Element}} objects in any namespace. + + + +

UI

+ +

User agents are encouraged to implement native media fullscreen controls in terms of +{{Element/requestFullscreen()}} and {{Document/exitFullscreen()}}. + +

If the end user instructs the user agent to end a fullscreen session initiated via +{{Element/requestFullscreen()}}, fully exit fullscreen given the +top-level traversable's active document. + +

The user agent may end any fullscreen session without instruction from the end user +or call to {{Document/exitFullscreen()}} whenever the user agent deems it necessary. + + + +

Rendering

+ +

This section is to be interpreted equivalently to the Rendering section of HTML. [[!HTML]] + + +

:fullscreen pseudo-class

+ +

The :fullscreen pseudo-class must match any +element element for which one of the following conditions is true: + +

+ +

This makes it different from the +{{DocumentOrShadowRoot/fullscreenElement}} API, which returns the topmost fullscreen element. + +

User-agent level style sheet defaults

+ + +
+@namespace "http://www.w3.org/1999/xhtml";
+
+*|*:not(:root):fullscreen {
+  position:fixed !important;
+  inset:0 !important;
+  margin:0 !important;
+  box-sizing:border-box !important;
+  min-width:0 !important;
+  max-width:none !important;
+  min-height:0 !important;
+  max-height:none !important;
+  width:100% !important;
+  height:100% !important;
+  transform:none !important;
+
+  /* intentionally not !important */
+  object-fit:contain;
+}
+
+iframe:fullscreen {
+  border:none !important;
+  padding:0 !important;
+}
+
+*|*:not(:root):fullscreen::backdrop {
+  background:black;
+}
+
+ + + +

Permissions Policy +Integration

+ +

This specification defines a policy-controlled feature identified by the string +"fullscreen". Its default allowlist is +'self'. + +

+

A document's permissions policy determines whether any content in that +document is allowed to go fullscreen. If disabled in any document, no content in the document will +be allowed to use fullscreen. + +

The <{iframe/allowfullscreen}> attribute of the HTML <{iframe}> element affects the container +policy for any document nested in that iframe. Unless overridden by the <{iframe/allow}> +attribute, setting <{iframe/allowfullscreen}> on an iframe is equivalent to <iframe +allow="fullscreen *">, as described in +[[permissions-policy#iframe-allowfullscreen-attribute]]. +

+ + + +

Security and Privacy Considerations

+ +

User agents should ensure, e.g. by means of an overlay, that the end user is aware something is +displayed fullscreen. User agents should provide a means of exiting fullscreen that always works and +advertise this to the user. This is to prevent a site from spoofing the end user by recreating the +user agent or even operating system environment when fullscreen. See also the definition of +{{Element/requestFullscreen()}}. + +

To enable content in a child navigable to go fullscreen, it needs to be specifically +allowed via permissions policy, either through the <{iframe/allowfullscreen}> attribute of the HTML +<{iframe}> element, or an appropriate declaration in the <{iframe/allow}> attribute of the HTML +<{iframe}> element, or through a `Permissions-Policy` HTTP header +delivered with the document through which it is nested. + +

This prevents e.g. content from third parties to go fullscreen without explicit permission. + + + +

+ +This specification previously hosted the definitions of ::backdrop +and the concept of the document's top layer. + + + +

Acknowledgments

+ +

Many thanks to Robert O'Callahan for designing the initial model and being awesome. + + +

Thanks to +Andy Earnshaw, +Changwan Hong, +Chris Pearce, +Darin Fisher, +Dave Tapuska, +fantasai, +Giuseppe Pascale, +Glenn Maynard, +Ian Clelland, +Ian Hickson, +Ignacio Solla, +João Eiras, +Josh Soref, +Kagami Sascha Rosylight, +Matt Falkenhagen, +Mihai Balan, +Mounir Lamouri, +Øyvind Stenhaug, +Pat Ladd, +Rafał Chłodnicki, +Riff Jiang, +Rune Lillesveen, +Sigbjørn Vik, +Simon Pieters, +Tab Atkins-Bittner, +Takayoshi Kochi, +Theresa O'Connor, +triple-underscore, +Vincent Scheib, and +Xidorn Quan +for also being awesome. + +

This standard is edited by Philip Jägenstedt +(Google, +philip@foolip.org). It was originally written by +Anne van Kesteren +(Apple, annevk@annevk.nl). +Tantek Çelik +(Mozilla, +tantek@cs.stanford.edu) sorted out legal hassles.