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 @@ +<pre class=metadata> +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 +</pre> + +<pre class=link-defaults> +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 +</pre> + +<pre class=anchors> +urlPrefix: https://w3c.github.io/screen-orientation/#dfn- + type: dfn + text: triggered by a user generated orientation change +</pre> + +<pre class=biblio> +{ + "CSS": { + "aliasOf": "CSS2" + }, + "SVG": { + "aliasOf": "SVG11" + } +} +</pre> + + + +<h2 id=terminology>Terminology</h2> + +<p>This specification depends on the Infra Standard. [[!INFRA]] + +<p>Most terminology used in this specification is from CSS, DOM, HTML, and Web IDL. [[!CSS]] +[[!DOM]] [[!HTML]] [[!WEBIDL]] + + + +<h2 id=model>Model</h2> + +<p>All <a>elements</a> have an associated <dfn>fullscreen flag</dfn>. Unless stated otherwise it is +unset. + +<p>All <{iframe}> <a>elements</a> have an associated <dfn>iframe fullscreen flag</dfn>. Unless +stated otherwise it is unset. + +<p>All <a for=/>documents</a> have an associated <dfn export>fullscreen element</dfn>. The +<a>fullscreen element</a> is the topmost <a>element</a> in the <a for=/>document</a>'s +<a>top layer</a> whose <a>fullscreen flag</a> is set, if any, and null otherwise. + +<p>All <a for=/>documents</a> have an associated <dfn>list of pending fullscreen events</dfn>, which +is an <a>ordered set</a> of (<a>string</a>, <a>element</a>) <a>tuples</a>. It is initially empty. + +<p>To <dfn>fullscreen an <var>element</var></dfn>: + +<ol> + <li><p>Let <var>hideUntil</var> be the result of running <a>topmost popover ancestor</a> given + <var>element</var>, null, and false. + + <li><p>If <var>hideUntil</var> is null, then set <var>hideUntil</var> to <var>element</var>'s + <span>node document</span>. + + <li><p>Run <a>hide all popovers until</a> given <var>hideUntil</var>, false, and true. + + <li><p>Set <var>element</var>'s <a>fullscreen flag</a>. + + <li><p><a>Remove from the top layer immediately</a> given <var>element</var>. + + <li><a>Add to the top layer</a> given <var>element</var>. +</ol> + +<p>To <dfn>unfullscreen an <var>element</var></dfn>, unset <var>element</var>'s +<a>fullscreen flag</a> and <a>iframe fullscreen flag</a> (if any), and +<a>remove from the top layer immediately</a> given <var>element</var>. + +<p>To <dfn>unfullscreen a <var>document</var></dfn>, +<a lt="unfullscreen an element">unfullscreen</a> all <a>elements</a>, within <var>document</var>'s +<a>top layer</a>, whose <a>fullscreen flag</a> is set. + +<hr> + +<div algorithm> +<p>To <dfn>fully exit fullscreen</dfn> a <a for=/>document</a> <var>document</var>, run these steps: + +<ol> + <li><p>If <var>document</var>'s <a>fullscreen element</a> is null, terminate these steps. + + <li><p><a lt="unfullscreen an element">Unfullscreen elements</a> whose <a>fullscreen flag</a> is + set, within <var>document</var>'s <a>top layer</a>, except for <var>document</var>'s + <a>fullscreen element</a>. + + <li><p><a>Exit fullscreen</a> <var>document</var>. +</ol> +</div> + +<div algorithm="fullscreen removing steps"> +<p id=removing-steps>Whenever the <a>removing steps</a> run with a <var>removedNode</var>, run +these steps: + +<ol> + <li><p>Let <var>document</var> be <var>removedNode</var>'s <a>node document</a>. + + <li><p>Let <var>nodes</var> be <var>removedNode</var>'s + <a>shadow-including inclusive descendants</a> that have their <a>fullscreen flag</a> set, in + <a>shadow-including tree order</a>. + + <li> + <p><a>For each</a> <var>node</var> in <var>nodes</var>: + + <ol> + <li><p>If <var>node</var> is <var>document</var>'s <a>fullscreen element</a>, + <a>exit fullscreen</a> <var>document</var>. + + <li><p>Otherwise, <a lt="unfullscreen an element">unfullscreen <var>node</var></a>. + + <li> + <p>If <var>document</var>'s <a>top layer</a> <a for=set>contains</a> <var>node</var>, + <a>remove from the top layer immediately</a> given <var>node</var>. + + <p class=note>Other specifications can add and remove elements from <a>top layer</a>, so + <var>node</var> might not be <var>document</var>'s <a>fullscreen element</a>. For example, + <var>node</var> could be an open <{dialog}> element. + </ol> +</ol> +</div> + +<p>Whenever the <a>unloading document cleanup steps</a> run with a <var>document</var>, +<a>fully exit fullscreen</a> <var>document</var>. + +<hr> + +<p><dfn>Fullscreen is supported</dfn> if there is no previously-established user preference, +security risk, or platform limitation. + +<hr> + +<div algorithm> +<p>To <dfn>run the fullscreen steps</dfn> for a <a>document</a> <var>document</var>, run these +steps: + +<ol> + <li><p>Let <var>pendingEvents</var> be <var>document</var>'s + <a>list of pending fullscreen events</a>. + + <li><p><a for=set>Empty</a> <var>document</var>'s <a>list of pending fullscreen events</a>. + + <li> + <p><a>For each</a> (<var>type</var>, <var>element</var>) in <var>pendingEvents</var>: + + <ol> + <li><p>Let <var>target</var> be <var>element</var> if <var>element</var> is <a>connected</a> + and its <a>node document</a> is <var>document</var>, and otherwise let <var>target</var> be + <var>document</var>. + + <li><p><a>Fire an event</a> named <var>type</var>, with its {{Event/bubbles}} and + {{Event/composed}} attributes set to true, at <var>target</var>. + </ol> +</ol> + +<p class=note>These steps integrate with the <a for=/>event loop</a> defined in HTML. [[!HTML]] +</div> + + + +<h2 id=api>API</h2> + +<pre class=idl> +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; +}; +</pre> +<!-- The event handler attributes are intentially not in a partial DocumentAndElementEventHandlers + interface, which is implemented by Document and HTMLElement, not Element. --> + +<dl class=domintro> + <dt><code><var>promise</var> = <var>element</var> . <a method for=Element lt=requestFullscreen()>requestFullscreen([<var>options</var>])</a></code> + <dd> + Displays <var>element</var> fullscreen and resolves <var>promise</var> when done. + + When supplied, <var>options</var>'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. + + <dt><code><var>document</var> . {{Document/fullscreenEnabled}}</code> + <dd><p>Returns true if <var>document</var> has the ability to display <a>elements</a> fullscreen + and <a>fullscreen is supported</a>, or false otherwise. + + <dt><code><var>promise</var> = <var>document</var> . {{Document/exitFullscreen()}}</code> + <dd><p>Stops <var>document</var>'s <a>fullscreen element</a> from being displayed fullscreen and + resolves <var>promise</var> when done. + + <dt><code><var>document</var> . {{DocumentOrShadowRoot/fullscreenElement}}</code> + <dd><p>Returns <var>document</var>'s <a>fullscreen element</a>. + + <dt><code><var>shadowroot</var> . {{DocumentOrShadowRoot/fullscreenElement}}</code> + <dd><p>Returns <var>shadowroot</var>'s <a>fullscreen element</a>. +</dl> + +<p>A <dfn>fullscreen element ready check</dfn> for an <a>element</a> <var>element</var> returns true +if all of the following are true, and false otherwise: + +<ul> + <li><p><var>element</var> is <a>connected</a>. + + <li><p><var>element</var>'s <a>node document</a> is <a>allowed to use</a> the "<code><a + data-lt="fullscreen-feature">fullscreen</a></code>" feature. + <!-- cross-process, recursive --> + + <li><p><var>element</var> <a for=Element>namespace</a> is not the <a>HTML namespace</a> or + <var>element</var>'s <a>popover visibility state</a> is <a for="popover visibility + state">hidden</a>. +</ul> + +<div algorithm="requestFullscreen(options)"> +<p>The <dfn method for=Element><code>requestFullscreen(<var>options</var>)</code></dfn> method steps +are: + +<ol> + <li><p>Let <var>pendingDoc</var> be <a>this</a>'s <a>node document</a>. + + <li><p>Let <var>promise</var> be a new promise. + + <li><p>If <var>pendingDoc</var> is not <a>fully active</a>, then reject <var>promise</var> with a + {{TypeError}} exception and return <var>promise</var>. + + <li><p>Let <var>error</var> be false. + + <li> + <p>If any of the following conditions are false, then set <var>error</var> to true: + + <ul> + <li><p><a>This</a>'s <a for=Element>namespace</a> is the <a>HTML namespace</a> or + <a>this</a> is an + <a href=https://www.w3.org/TR/SVG11/struct.html#SVGElement>SVG <code>svg</code></a> or + <a href=https://www.w3.org/Math/draft-spec/chapter2.html#interf.toplevel>MathML <code>math</code></a> + element. [[!SVG]] [[!MATHML]] + + <li><p><a>This</a> is not a <{dialog}> element. + + <li><p>The <a>fullscreen element ready check</a> for <a>this</a> returns true. + + <li><p><a>Fullscreen is supported</a>. + + <li><p><a>This</a>'s <a>relevant global object</a> has <a>transient activation</a> or the + algorithm is <a>triggered by a user generated orientation change</a>. + </ul> + + <li><p>If <var>error</var> is false, then <a>consume user activation</a> given + <var>pendingDoc</var>'s <a>relevant global object</a>. + + <li><p>Return <var>promise</var>, and run the remaining steps <a>in parallel</a>. + + <li> + <p>If <var>error</var> is false, then resize <var>pendingDoc</var>'s <a>node navigable</a>'s + <a for=navigable>top-level traversable</a>'s <a for=navigable>active document</a>'s viewport's + dimensions, optionally taking into account + <var>options</var>["{{FullscreenOptions/navigationUI}}"]: + <!-- cross-process --> + + <table> + <thead> + <tr> + <th>value</th> + <th>viewport dimensions</th> + </tr> + </thead> + <tbody> + <tr> + <td>"<dfn enum-value for="FullscreenNavigationUI"><code>hide</code></dfn>"</td> + <td>full dimensions of the screen of the output device</td> + </tr> + <tr> + <td>"<dfn enum-value for="FullscreenNavigationUI"><code>show</code></dfn>"</td> + <td>dimensions of the screen of the output device clamped to allow the user agent to show page navigation controls</td> + </tr> + <tr> + <td>"<dfn enum-value for="FullscreenNavigationUI"><code>auto</code></dfn>"</td> + <td>user-agent defined, but matching one of the above</td> + </tr> + </tbody> + </table> + + <p>Optionally display a message how the end user can revert this. + + <li> + <p>If any of the following conditions are false, then set <var>error</var> to true: + + <ul> + <li><p><a>This</a>'s <a>node document</a> is <var>pendingDoc</var>. + + <li><p>The <a>fullscreen element ready check</a> for <a>this</a> returns true. + <!-- cross-process; check is only needed on pending as it is recursive already --> + </ul> + + <li> + <p>If <var>error</var> is true: + + <ol> + <li><p><a for=set>Append</a> ({{fullscreenerror}}, <a>this</a>) to + <var>pendingDoc</var>'s <a>list of pending fullscreen events</a>. + + <li><p>Reject <var>promise</var> with a {{TypeError}} exception and terminate these + steps. + </ol> + + <li><p>Let <var>fullscreenElements</var> be an <a>ordered set</a> initially consisting of + <a>this</a>. + + <li> + <p>While true: + + <ol> + <li><p>Let <var>last</var> be the last <a for=list>item</a> of <var>fullscreenElements</var>. + + <li><p>Let <var>container</var> be <var>last</var>'s <a>node navigable</a>'s + <a for=navigable>container</a>. + + <li><p>If <var>container</var> is null, then <a>break</a>. + + <li><p><a for=set>Append</a> <var>container</var> to <var>fullscreenElements</var>. + </ol> + </li> + <!-- cross-process --> + + <li> + <p><a>For each</a> <var>element</var> in <var>fullscreenElements</var>: + + <ol> + <li><p>Let <var>doc</var> be <var>element</var>'s <a>node document</a>. + + <li> + <p>If <var>element</var> is <var>doc</var>'s <a>fullscreen element</a>, <a>continue</a>. + + <p class=note>No need to notify observers when nothing has changed. + + <li><p>If <var>element</var> is <a>this</a> and <a>this</a> is an <{iframe}> + <a>element</a>, then set <var>element</var>'s <a>iframe fullscreen flag</a>. + + <li><p><a lt="fullscreen an element">Fullscreen <var>element</var></a> within <var>doc</var>. + + <li><p><a for=set>Append</a> ({{fullscreenchange}}, <var>element</var>) to + <var>doc</var>'s <a>list of pending fullscreen events</a>. + </ol> + + <p class=note>The order in which elements are <a lt="fullscreen an element">fullscreened</a> + is not observable, because <a>run the fullscreen steps</a> is invoked in <a>tree order</a>. + + <li><p>Resolve <var>promise</var> with undefined. +</ol> + +<p class=note>Implementations with out-of-process <a for=/>navigables</a> are left as an exercise +to the reader. Input welcome on potential improvements. +</div> + +<p>The <dfn attribute for=Document><code>fullscreenEnabled</code></dfn> getter steps are to return +true if <a>this</a> is <a>allowed to use</a> the "<code><a +data-lt="fullscreen-feature">fullscreen</a></code>" feature and <a>fullscreen is supported</a>, and +false otherwise. + +<p>The <dfn attribute for=Document><code>fullscreen</code></dfn> getter steps are to return false if +<a>this</a>'s <a>fullscreen element</a> is null, and true otherwise. + +<p class=note>Use the {{DocumentOrShadowRoot/fullscreenElement}} attribute instead. + +<div algorithm> +<p>The +<dfn attribute for=DocumentOrShadowRoot id=dom-document-fullscreenelement><code>fullscreenElement</code></dfn> +getter steps are: + +<ol> + <li><p>If <a>this</a> is a <a for=/>shadow root</a> and its <a for=DocumentFragment>host</a> is not + <a>connected</a>, then return null. + + <li><p>Let <var>candidate</var> be the result of <a>retargeting</a> <a>fullscreen element</a> + against <a>this</a>. + + <li><p>If <var>candidate</var> and <a>this</a> are in the same <a>tree</a>, then return + <var>candidate</var>. + + <li><p>Return null. +</ol> +</div> + +<p>A <a>document</a> is said to be a <dfn>simple fullscreen document</dfn> if there is exactly one +<a>element</a> in its <a>top layer</a> that has its <a>fullscreen flag</a> set. + +<p class=note>A <a>document</a> with two <a>elements</a> in its <a>top layer</a> can be a +<a>simple fullscreen document</a>. For example, in addition to the <a>fullscreen element</a> there +could be an open <{dialog}> element. + +<div algorithm> +<p>To <dfn>collect documents to unfullscreen</dfn> given <var>doc</var>, run these steps: + +<ol> + <li><p>Let <var>docs</var> be an <a>ordered set</a> consisting of <var>doc</var>. + + <li> + <p><a>While</a> true: + + <ol> + <li><p>Let <var>lastDoc</var> be <var>docs</var>'s last <a for=/>document</a>. + + <li><p>Assert: <var>lastDoc</var>'s <a>fullscreen element</a> is not null. + + <li><p>If <var>lastDoc</var> is not a <a>simple fullscreen document</a>, <a>break</a>. + + <li><p>Let <var>container</var> be <var>lastDoc</var>'s <a>node navigable</a>'s + <a for=navigable>container</a>. + + <li><p>If <var>container</var> is null, then <a>break</a>. + + <li><p>If <var>container</var>'s <a>iframe fullscreen flag</a> is set, <a>break</a>. + + <li><p><a for=set>Append</a> <var>container</var>'s <a>node document</a> to <var>docs</var>. + </ol> + + <li><p>Return <var>docs</var>. + + <p class=note>This is the set of documents for which the <a>fullscreen element</a> will be + <a lt="unfullscreen an element">unfullscreened</a>, but the last document in <var>docs</var> might + have more than one <a>element</a> in its <a>top layer</a> with the <a>fullscreen flag</a> set, + in which case that document will still remain in fullscreen. +</ol> +</div> + +<div algorithm> +<p>To <dfn>exit fullscreen</dfn> a <a for=/>document</a> <var>doc</var>, run these steps: + +<ol> + <li><p>Let <var>promise</var> be a new promise. + + <li><p>If <var>doc</var> is not <a>fully active</a> or <var>doc</var>'s <a>fullscreen element</a> + is null, then reject <var>promise</var> with a {{TypeError}} exception and return + <var>promise</var>. + + <li><p>Let <var>resize</var> be false. + + <li><p>Let <var>docs</var> be the result of + <a lt="collect documents to unfullscreen">collecting documents to unfullscreen</a> given + <var>doc</var>. + <!-- cross-process --> + + <li><p>Let <var>topLevelDoc</var> be <var>doc</var>'s <a>node navigable</a>'s + <a for=navigable>top-level traversable</a>'s <a for=navigable>active document</a>. + <!-- cross-process --> + + <li><p>If <var>topLevelDoc</var> is in <var>docs</var>, and it is a + <a>simple fullscreen document</a>, then set <var>doc</var> to <var>topLevelDoc</var> and + <var>resize</var> to true. + + <li><p>If <var>doc</var>'s <a>fullscreen element</a> is not <a>connected</a>: + <ol> + <li><p><a for=set>Append</a> ({{fullscreenchange}}, <var>doc</var>'s + <a>fullscreen element</a>) to <var>doc</var>'s + <a>list of pending fullscreen events</a>. + </ol> + + <li><p>Return <var>promise</var>, and run the remaining steps <a>in parallel</a>. + + <li><p>Run the [=fully unlock the screen orientation steps=] with <var>doc</var>. + + <li><p>If <var>resize</var> is true, resize <var>doc</var>'s viewport to its "normal" dimensions. + + <li><p>If <var>doc</var>'s <a>fullscreen element</a> is null, then resolve <var>promise</var> with + undefined and terminate these steps. + + <li><p>Let <var>exitDocs</var> be the result of + <a lt="collect documents to unfullscreen">collecting documents to unfullscreen</a> given + <var>doc</var>. + <!-- cross-process --> + + <li><p>Let <var>descendantDocs</var> be an <a>ordered set</a> consisting of <var>doc</var>'s + <a for=Document>descendant navigables</a>' <a for=navigable>active documents</a> whose + <a>fullscreen element</a> is non-null, if any, in <a>tree order</a>. + <!-- cross-process --> + + <li> + <p><a>For each</a> <var>exitDoc</var> in <var>exitDocs</var>: + + <ol> + <li><p><a for=set>Append</a> ({{fullscreenchange}}, <var>exitDoc</var>'s + <a>fullscreen element</a>) to <var>exitDoc</var>'s <a>list of pending fullscreen events</a>. + + <li><p>If <var>resize</var> is true, <a lt="unfullscreen a document">unfullscreen + <var>exitDoc</var></a>. + + <li><p>Otherwise, <a lt="unfullscreen an element">unfullscreen</a> <var>exitDoc</var>'s + <a>fullscreen element</a>. + </ol> + + <li> + <p><a>For each</a> <var>descendantDoc</var> in <var>descendantDocs</var>: + + <ol> + <li><p><a for=set>Append</a> ({{fullscreenchange}}, <var>descendantDoc</var>'s + <a>fullscreen element</a>) to <var>descendantDoc</var>'s + <a>list of pending fullscreen events</a>. + + <li><p><a lt="unfullscreen a document">Unfullscreen <var>descendantDoc</var></a>. + </ol> + + <p class=note>The order in which documents are <a lt="unfullscreen a document">unfullscreened</a> + is not observable, because <a>run the fullscreen steps</a> is invoked in <a>tree order</a>. + + <li><p>Resolve <var>promise</var> with undefined. +</ol> +</div> + +<p>The <dfn method for=Document><code>exitFullscreen()</code></dfn> method steps are to return the +result of running <a>exit fullscreen</a> on <a>this</a>. + +<hr> + +<p>The following are the <a>event handlers</a> (and their corresponding +<a>event handler event types</a>) that must be supported by {{Element}} and {{Document}} objects as +<a>event handler IDL attributes</a>: + +<table> + <thead> + <tr> + <th><a lt="event handlers">event handler</a> + <th><a>event handler event type</a> + <tbody> + <tr> + <td><dfn attribute for=Document,Element id=handler-document-onfullscreenchange><code>onfullscreenchange</code></dfn> + <td><dfn event for=Document,Element><code>fullscreenchange</code></dfn> + <tr> + <td><dfn attribute for=Document,Element id=handler-document-onfullscreenerror><code>onfullscreenerror</code></dfn> + <td><dfn event for=Document,Element><code>fullscreenerror</code></dfn> +</table> + +<p class=note>These are not supported by {{ShadowRoot}} or {{Window}} objects, and there are no +corresponding <a>event handler content attributes</a> for {{Element}} objects in any namespace. + + + +<h2 id=ui>UI</h2> + +<p>User agents are encouraged to implement native media fullscreen controls in terms of +{{Element/requestFullscreen()}} and {{Document/exitFullscreen()}}. + +<p>If the end user instructs the user agent to end a fullscreen session initiated via +{{Element/requestFullscreen()}}, <a>fully exit fullscreen</a> given the +<a for=/>top-level traversable</a>'s <a>active document</a>. + +<p>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. + + + +<h2 id=rendering>Rendering</h2> + +<p>This section is to be interpreted equivalently to the Rendering section of HTML. [[!HTML]] + + +<h3 id=:fullscreen-pseudo-class><code>:fullscreen</code> pseudo-class</h3> + +<p>The <dfn id=css-pc-fullscreen selector><code>:fullscreen</code></dfn> pseudo-class must match any +<a>element</a> <var>element</var> for which one of the following conditions is true: + +<ul> + <li><p><var>element</var>'s <a>fullscreen flag</a> is set. + + <li><p><var>element</var> is a <a>shadow host</a> and the result of <a>retargeting</a> its + <a>node document</a>'s <a>fullscreen element</a> against <var>element</var> is <var>element</var>. +</ul> + +<p class="note no-backref">This makes it different from the +{{DocumentOrShadowRoot/fullscreenElement}} API, which returns the topmost <a>fullscreen element</a>. + +<h3 id=user-agent-level-style-sheet-defaults>User-agent level style sheet defaults</h3> +<!-- HTML's "The CSS user agent style sheet and presentational hints" section uses this term --> + +<pre class=css> +@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; +} +</pre> + + + +<h2 id=permissions-policy-integration oldids=feature-policy-integration>Permissions Policy +Integration</h2> + +<p>This specification defines a <a>policy-controlled feature</a> identified by the string +"<code><dfn data-lt="fullscreen-feature">fullscreen</dfn></code>". Its <a>default allowlist</a> is +<code>'self'</code>. + +<div class="note"> +<p>A <a>document</a>'s <a for=Document>permissions policy</a> determines whether any content in that +document is allowed to go fullscreen. If disabled in any document, no content in the document will +be <a>allowed to use</a> fullscreen. + +<p>The <{iframe/allowfullscreen}> attribute of the HTML <{iframe}> element affects the <a>container +policy</a> for any document nested in that iframe. Unless overridden by the <{iframe/allow}> +attribute, setting <{iframe/allowfullscreen}> on an iframe is equivalent to <code><iframe +allow="fullscreen *"></code>, as described in +[[permissions-policy#iframe-allowfullscreen-attribute]]. +</div> + + + +<h2 id=security-and-privacy-considerations>Security and Privacy Considerations</h2> + +<p>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()}}. + +<p>To enable content in a <a>child navigable</a> 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 `<a http-header><code>Permissions-Policy</code></a>` HTTP header +delivered with the <a>document</a> through which it is nested. + +<p>This prevents e.g. content from third parties to go fullscreen without explicit permission. + + + +<h2 id=old-links class=no-num oldids="new-stacking-layer, top-layer, top-layer-add, ::backdrop-pseudo-element, css-pe-backdrop">Previously-hosted definitions</h2> + +This specification previously hosted the definitions of <a selector>::backdrop</a> +and the concept of the document's <a>top layer</a>. + + + +<h2 id=acknowledgments class=no-num>Acknowledgments</h2> + +<p>Many thanks to Robert O'Callahan for designing the initial model and being awesome. +<!-- https://wiki.mozilla.org/Gecko:FullScreenAPI --> + +<p>Thanks to +Andy Earnshaw, +Changwan Hong, +Chris Pearce, +Darin Fisher, +Dave Tapuska, +<i>fantasai</i>, +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. + +<p>This standard is edited by <a lang=sv href=https://foolip.org/>Philip Jägenstedt</a> +(<a href=https://google.com/>Google</a>, +<a href=mailto:philip@foolip.org>philip@foolip.org</a>). It was originally written by +<a lang=nl href=https://annevankesteren.nl/>Anne van Kesteren</a> +(<a href=https://www.apple.com/>Apple</a>, <a href=mailto:annevk@annevk.nl>annevk@annevk.nl</a>). +<a lang=tr href=http://tantek.com/>Tantek Çelik</a> +(<a class="p-org org h-org h-card" href=https://www.mozilla.org/>Mozilla</a>, +<a href=mailto:tantek@cs.stanford.edu>tantek@cs.stanford.edu</a>) sorted out legal hassles.