[mediaqueries-5] Import display-modes (#6343)

mediaqueries-5/Overview.bs

@@ -1292,6 +1292,105 @@ Vertical Viewport Segments: the '@media/vertical-viewport-segments' feature</h3>
 		<pre>@media (horizontal-viewport-segments: 2) and (vertical-viewport-segments: 1) { … }</pre>
 	</div>
 
+<h3 id=display-modes>
+Display Modes: the ''display-mode'' media feature </h3>
+
+	<pre class='descdef mq'>
+	Name: display-mode
+	Value: fullscreen | standalone | minimal-ui | browser
+	For: @media
+	Type: discrete
+	</pre>
+
+	The 'display-mode' media feature represents the [=display mode=] of the web application.
+	Child browsing contexts reflect the [=display mode=] of their [=top-level browsing context=].
+
+	A <dfn>display mode</dfn> represents
+	how the web application is being presented within the context of an OS (e.g., in fullscreen, etc.).
+	Display modes correspond to user interface (UI) metaphors
+	and functionality in use on a given platform.
+	The UI conventions of the display modes are purely advisory
+	and implementers are free to interpret them how they best see fit.
+
+	This specification defines the following [=display modes=]:
+	<dl dfn-for="display mode" export>
+		<dt><dfn>fullscreen</dfn>
+		<dd>
+			The web application is displayed with browser UI elements hidden
+			and takes up the entirety of the available display area.
+
+		<dt><dfn>standalone</dfn>
+		<dd>
+			The web application is displayed to look and feel like a standalone native application.
+			This can include the application having a different window,
+			its own icon in the application launcher, etc.
+			In this mode,
+			the user agent excludes standard browser UI elements
+			such as an URL bar,
+			but standard system UI elements,
+			such as window decorations, a system status bar, and/or a system back button,
+			remain available.
+
+		<dt><dfn>minimal-ui</dfn>
+		<dd>
+			This mode is similar to [=display mode/standalone=],
+			but provides the end-user with some means to access
+			a minimal set of UI elements for controlling navigation
+			(i.e., back, forward, reload, and perhaps some way of viewing the document's address).
+			A user agent may include other platform specific UI elements,
+			such as "share" and "print" buttons
+			or whatever is customary on the platform and user agent.
+
+		<dt><dfn>browser</dfn>
+		<dd>
+			The web application is displayed using the platform-specific convention
+			for opening hyperlinks in the user agent
+			(e.g., in a browser tab or a new window).
+	</dl>
+
+	<details class="note">
+		<summary>The [=display mode/fullscreen=] [=display mode=] is distinct from the [[FULLSCREEN|Fullscreen API]].</summary>
+
+		The [=display mode/fullscreen=] [=display mode=] describes the fullscreen state of the browser viewport,
+		while the [[FULLSCREEN|Fullscreen API]] operates on an element contained within the viewport.
+		As such, a web application can have its [=display mode=] set to [=display mode/fullscreen=],
+		even while {{fullscreenElement}} returns <code>null</code>,
+		and {{fullscreenEnabled}} returns <code>false</code>.
+
+		The ''fullscreen'' <a>display mode</a> is also not directly related
+		to the CSS '':fullscreen'' pseudo-class.
+		The '':fullscreen'' pseudo-class matches an element
+		exclusively when that element is put into the fullscreen element stack.
+		However, a side effect of calling the {{requestFullscreen()}} method
+		on an element using the [[FULLSCREEN|Fullscreen API]]
+		can be that the browser enters a fullscreen mode at the OS-level,
+		in which case both '':fullscreen'' and ''(display-mode: fullscreen)'' will match.
+	</details>
+
+	<div class="example">
+		On some platforms,
+		it is possible for a user--
+		or a  [[APPMANIFEST|Web Application Manifest]]--
+		to put a web application into fullscreen
+		without invoking the [[FULLSCREEN|Fullscreen API]].
+		When this happens,
+		the '':fullscreen'' pseudo class will not match,
+		but ''(display-mode: fullscreen)'' will match.
+		This is exemplified in CSS code below:
+
+		<pre class="lang-css">
+			/* applies when the viewport is fullscreen */
+			@media (display-mode: fullscreen) {
+				...
+			}
+
+			/* applies when an element is fullscreen */
+			#game:fullscreen {
+				...
+			}
+		</pre>
+	</div>
+
 <!--
 ████████  ████  ██████  ████████         ███████  ██     ██    ███    ██       ████ ████████ ██    ██
 ██     ██  ██  ██    ██ ██     ██       ██     ██ ██     ██   ██ ██   ██        ██     ██     ██  ██
@@ -3277,7 +3376,7 @@ Changes Since the 2020-07-31 Working Draft</h3>
 The following additions were made to this module since the
 <a href="https://www.w3.org/TR/2020/WD-mediaqueries-5-20200731/">2020-07-31 Working Draft</a>:
 
-None yet.
+	* Adopted 'display-mode' from [[APPMANIFEST]].
 
 <h3 id="changes-since-2020-07-15">
 Changes Since the 2020-07-15 Working Draft</h3>