[mediaqueries-5] Move the definition of display-mode back to APPMANIFEST

Closes w3c#7306
Closes w3c#7307

Author: mgiuca

mediaqueries-5/Overview.bs

@@ -1306,104 +1306,112 @@ Display Modes: the ''display-mode'' media feature </h3>
 	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 export>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>
+	The '@media/display-mode' media feature describes the mode in which the current [=browsing context=] is
+	currently being presented to the end user.  In child browsing contexts, the [=display mode=] must
+	match that of the [=top-level browsing context=].
+
+	This feature is primarily used to determine which [=display mode=] the user agent has applied to
+	an [=application context=]. As such, the values of this feature correspond to the [=display
+	mode|display modes=] defined in [[APPMANIFEST]]. However, it can also be used in non-application
+	contexts to determine whether the viewport is in other modes, such as
+	fullscreen or picture-in-picture.
+
+
+	<dl dfn-type=value dfn-for="@media/display-mode">
 		<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.
+			The browsing context is displayed with browser UI elements hidden and takes up the entirety of
+			the available display area. The fullscreen context may have been caused by the [=display
+			mode/fullscreen=] display mode in the [=application manifest=], by the {{requestFullscreen()}}
+			method of the [[FULLSCREEN|Fullscreen API]], or through some other means (such as the user
+			manually activating fullscreen mode using the user agent's built-in controls).
+
+			Corresponds to the [=display mode/fullscreen=] display mode.
 
 		<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.
+			The [=display mode/standalone=] display mode is in use. Only applicable in an [=application
+			context=].
 
 		<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.
+			The [=display mode/minimal-ui=] display mode is in use. Only applicable in an [=application
+			context=].
 
 		<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).
+			The browsing context is displayed using the platform-specific convention for opening
+			hyperlinks in the user agent (e.g., in a browser tab or web browser window with controls such
+			as an address bar). This should be used for non-[=application context|application contexts=]
+			where no other display mode is appropriate.
+
+			Corresponds to the [=display mode/browser=] display mode.
 
 		<dt><dfn>picture-in-picture</dfn>
 		<dd>
 			This mode allows users to continue consuming media while they interact
 			with other sites or applications on their device.
-			The web application is displayed in a floating and always-on-top window.
+			The browsing context is displayed in a floating and always-on-top window.
 			A user agent may include other platform specific UI elements,
 			such as "back-to-tab" and "site information" buttons
 			or whatever is customary on the platform and user agent.
 
 	</dl>
 
-	<details class="note">
-		<summary>The [=display mode/fullscreen=] [=display mode=] is distinct from the [[FULLSCREEN|Fullscreen API]].</summary>
+	<div class="example">
+		For example, the [=application manifest=] can request the [=display mode/standalone=] [=display
+		mode=] as follows:
+		<pre class="lang-json">
+			{
+				"display": "standalone"
+			}
+		</pre>
+
+		This media query can be used to determine whether the user agent has actually applied the
+		[=display mode/standalone=] mode:
 
-		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>.
+		<pre class="lang-css">@media (display-mode: standalone) { … }</pre>
 
-		The ''fullscreen'' <a>display mode</a> is also not directly related
+		The user agent could set '@media/display-mode' to any of the other values, depending on the
+		actual mode currently in use.
+	</div>
+
+	<details class="note">
+		<summary>The [=display mode/fullscreen=] [=display mode=] is distinct from the
+		[[FULLSCREEN|Fullscreen API]].</summary>
+
+		The ''fullscreen'' value for [=display-mode=] is 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) {
-				...
-			}
+		<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>
+	</details>
 
-			/* applies when an element is fullscreen */
-			#game:fullscreen {
-				...
-			}
-		</pre>
-	</div>
+	Note: Additional values for this media feature may be added in the future to
+	match new [=display mode|display modes=] added to [[APPMANIFEST]].
 
 <!--
 ████████  ████  ██████  ████████         ███████  ██     ██    ███    ██       ████ ████████ ██    ██
@@ -3411,6 +3419,8 @@ In addition to editorial changes and minor clarifications,
 the following changes and additions were made to this module since the
 <a href="https://www.w3.org/TR/2021/WD-mediaqueries-5-20211218/">2021-12-18 Working Draft</a>:
 
+* Moved 'display mode' definition back to [[APPMANIFEST]] ('display-mode' media feature remains
+	here). (See <a href="https://github.com/w3c/csswg-drafts/issues/7306">Issue 7306</a>)
 * Establish a normative reference for [[Display-P3]]
 * Disallow use of ''layer'' as a media type, rather than merely treat it as an unknown one, for compatibility with [=cascade layers=].
 * Clarify intent of 'prefers-reduced-motion'
@@ -3423,7 +3433,7 @@ In addition to editorial changes and minor clarifications,
 the following changes and 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>:
 
-	* Adopted 'display-mode' from [[APPMANIFEST]].
+	* Adopted 'display mode' definition and media feature from [[APPMANIFEST]].
 		(See <a href="https://github.com/w3c/csswg-drafts/issues/6343">Issue 6343</a>)
 	* Dropped the media features what were meant to query about the geometry of the video plane
 		in <a href="#video-prefixed-features">bi-plane implementations</a>: