DO NOT MERGE: Technical review for Window Management API docs

files/en-us/web/api/element/requestfullscreen/index.md

@@ -165,9 +165,9 @@ If you wanted to make the element fullscreen on the primary OS screen, you could
 
 ```js
 try {
-  const primaryScreen = (await getScreenDetails()).screens.filter(
+  const primaryScreen = (await getScreenDetails()).screens.find(
     (screen) => screen.isPrimary,
-  )[0];
+  );
   await document.body.requestFullscreen({ screen: primaryScreen });
 } catch (err) {
   console.error(err.name, err.message);

files/en-us/web/api/screen/change_event/index.md

@@ -40,8 +40,8 @@ An event of type `change`, the event object of which is structurally equivalent
 ## Examples
 
 ```js
-const firstScreen = (await window.getScreenDetails())[0];
-firstScreen.addEventListener("change", async (event) => {
+const firstScreen = (await window.getScreenDetails()).screens[0];
+firstScreen.addEventListener("change", (event) => {
   console.log("The first screen has changed.", event, firstScreen);
 });
 ```

files/en-us/web/api/screen/index.md

@@ -38,6 +38,19 @@ _Also inherits properties from its parent {{domxref("EventTarget")}}_.
 - {{DOMxRef("Screen.mozBrightness")}} {{Non-standard_Inline}} {{Deprecated_Inline}}
   - : Controls the brightness of a device's screen. A double between 0 and 1.0 is expected.
 
+## Non-standard properties
+
+The following properties are standardized as part of the [Window Management API](/en-US/docs/Web/API/Window_Management_API), thus we have chosen to document their standard form, which is available on the {{domxref("ScreenDetailed")}} interface. However, non-standard versions of these properties are available on the `Screen` interface.
+
+- {{domxref("ScreenDetailed.availLeft", "Screen.availLeft")}} {{ReadOnlyInline}} {{Non-standard_Inline}}
+  - : A number representing the x-coordinate (left-hand edge) of the available screen area.
+- {{domxref("ScreenDetailed.availTop", "Screen.availTop")}} {{ReadOnlyInline}} {{Non-standard_Inline}}
+  - : A number representing the y-coordinate (top edge) of the available screen area.
+- {{domxref("ScreenDetailed.left", "Screen.left")}} {{ReadOnlyInline}} {{Non-standard_Inline}}
+  - : A number representing the x-coordinate (left-hand edge) of the total screen area.
+- {{domxref("ScreenDetailed.top", "Screen.top")}} {{ReadOnlyInline}} {{Non-standard_Inline}}
+  - : A number representing the y-coordinate (top edge) of the total screen area.
+
 ## Instance methods
 
 _Also inherits methods from its parent {{domxref("EventTarget")}}_.
@@ -54,7 +67,7 @@ _Also inherits methods from its parent {{domxref("EventTarget")}}_.
 - {{DOMxRef("Screen.orientationchange_event", "orientationchange")}} {{Deprecated_Inline}} {{Non-standard_Inline}}
   - : Fires when the screen orientation changes.
 
-## Example
+## Examples
 
 ```js
 if (screen.pixelDepth < 8) {

files/en-us/web/api/screen/isextended/index.md

@@ -13,7 +13,7 @@ browser-compat: api.Screen.isExtended
 The **`isExtended`** read-only property of the
 {{domxref("Screen")}} interface returns `true` if the user's device has multiple screens, and `false` if not.
 
-This property is most commonly accessed via `window.screen.isExtended`, and provides a useful test to see if multiple screens are available before attempting to create a multi-window, multi-screen layout using the [Window Management API](/en-US/docs/Web/API/Window_Management_API). However, since {{domxref("ScreenDetailed")}} inherits from `Screen`, `isExtended` is also available on all `ScreenDetailed` object instances contained inside the {{domxref("ScreenDetails")}} object returned by {{domxref("Window.getScreenDetails()")}}. When multiple screens are available, all `isExtended` properties will be `true`.
+This property is typically accessed via `window.screen.isExtended`, and provides a useful test to see if multiple screens are available before attempting to create a multi-window, multi-screen layout using the [Window Management API](/en-US/docs/Web/API/Window_Management_API).
 
 ## Value
 

files/en-us/web/api/screendetailed/availleft/index.md

@@ -13,21 +13,34 @@ browser-compat: api.ScreenDetailed.availLeft
 The **`availLeft`** read-only property of the
 {{domxref("ScreenDetailed")}} interface is a number representing the x-coordinate (left-hand edge) of the available screen area inside the OS virtual screen arrangement, relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin).
 
-This is equal to the {{domxref("ScreenDetailed.left")}} property, plus the width of any OS UI element drawn on the left of the screen. Windows cannot be placed in those areas, so `availLeft` is useful for giving you the left boundary of the actual area you've got available.
+This is equal to the {{domxref("ScreenDetailed.left")}} property, plus the width of any OS UI element drawn on the left of the screen. Windows cannot be placed in those areas, so `availLeft` is useful for giving you the left boundary of the actual area available to open or place windows.
+
+> **Note:** A non-standard implementation of the `availLeft` property is available on the `Screen` interface in all browsers. This represents the x-coordinate (left-hand edge) of the _current_ screen's available area (i.e. the screen containing the browser window the code is being run in). See the [Non-standard example](#non-standard_example) below for usage details, and see the [`Screen`](/en-US/docs/Web/API/Screen#browser_compatibility) reference page for browser support information relating to the non-standard implementation.
 
 ## Value
 
 A number.
 
 ## Examples
 
+### Window Management API example
+
 ```js
+// Available in browsers that support the Window Management API
 const screenDetails = await window.getScreenDetails();
 
 // Return the availLeft value of the first screen
 const screen1AvailLeft = screenDetails.screens[0].availLeft;
 ```
 
+### Non-standard example
+
+```js
+// Available in all browsers
+// Return the availLeft value of the current screen
+const screenAvailLeft = window.screen.availLeft;
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/screendetailed/availtop/index.md

@@ -13,21 +13,34 @@ browser-compat: api.ScreenDetailed.availTop
 The **`availTop`** read-only property of the
 {{domxref("ScreenDetailed")}} interface is a number representing the y-coordinate (top edge) of the available screen area inside the OS virtual screen arrangement, relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin).
 
-This is equal to the {{domxref("ScreenDetailed.top")}} property, plus the height of any OS UI element drawn at the top of the screen. Windows cannot be placed in those areas, so `availTop` is useful for giving you the top boundary of the actual area you've got available.
+This is equal to the {{domxref("ScreenDetailed.top")}} property, plus the height of any OS UI element drawn at the top of the screen. Windows cannot be placed in those areas, so `availTop` is useful for giving you the top boundary of the actual area available to open or place windows.
+
+> **Note:** A non-standard implementation of the `availTop` property is available on the `Screen` interface in all browsers. This represents the y-coordinate (top edge) of the _current_ screen's available area (i.e. the screen containing the browser window the code is being run in). See the [Non-standard example](#non-standard_example) below for usage details, and see the [`Screen`](/en-US/docs/Web/API/Screen#browser_compatibility) reference page for browser support information relating to the non-standard implementation.
 
 ## Value
 
 A number.
 
 ## Examples
 
+### Window Management API example
+
 ```js
+// Available in browsers that support the Window Management API
 const screenDetails = await window.getScreenDetails();
 
 // Return the availTop value of the first screen
 const screen1AvailTop = screenDetails.screens[0].availTop;
 ```
 
+### Non-standard example
+
+```js
+// Available in all browsers
+// Return the availTop value of the current screen
+const screenAvailTop = window.screen.availTop;
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/screendetailed/devicepixelratio/index.md

@@ -11,7 +11,12 @@ browser-compat: api.ScreenDetailed.devicePixelRatio
 {{APIRef("Window Management API")}}{{SeeCompatTable}}
 
 The **`devicePixelRatio`** read-only property of the
-{{domxref("ScreenDetailed")}} interface is a number representing the screen's device pixel ratio. This is the same as the value returned by {{domxref("Window.devicePixelRatio")}} (although that property always returns the device pixel ratio for the {{domxref("ScreenDetails.currentScreen", "current screen", "", "nocode")}}) — see that page for more information about device pixel ratios in general.
+{{domxref("ScreenDetailed")}} interface is a number representing the screen's device pixel ratio.
+
+This is the same as the value returned by {{domxref("Window.devicePixelRatio")}}, except that `Window.devicePixelRatio`:
+
+- always returns the device pixel ratio for the {{domxref("ScreenDetails.currentScreen", "current screen", "", "nocode")}}.
+- also includes scaling of the window itself, i.e. page zoom (at least on some browser implementations).
 
 ## Value
 

files/en-us/web/api/screendetailed/index.md

@@ -20,7 +20,7 @@ The **`ScreenDetailed`** interface of the [Window Management API](/en-US/docs/We
 _Inherits properties from its parent, {{DOMxRef("Screen")}}._
 
 - {{domxref("ScreenDetailed.availLeft", "availLeft")}} {{ReadOnlyInline}} {{Experimental_Inline}}
-  - : A number representing the x-coordinate (left hand edge) of the available screen area.
+  - : A number representing the x-coordinate (left-hand edge) of the available screen area.
 - {{domxref("ScreenDetailed.availTop", "availTop")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : A number representing the y-coordinate (top edge) of the available screen area.
 - {{domxref("ScreenDetailed.devicePixelRatio", "devicePixelRatio")}} {{ReadOnlyInline}} {{Experimental_Inline}}
@@ -32,7 +32,7 @@ _Inherits properties from its parent, {{DOMxRef("Screen")}}._
 - {{domxref("ScreenDetailed.label", "label")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : A string providing a descriptive label for the screen, for example "Built-in Retina Display".
 - {{domxref("ScreenDetailed.left", "left")}} {{ReadOnlyInline}} {{Experimental_Inline}}
-  - : A number representing the x-coordinate (left hand edge) of the total screen area.
+  - : A number representing the x-coordinate (left-hand edge) of the total screen area.
 - {{domxref("ScreenDetailed.top", "top")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : A number representing the y-coordinate (top edge) of the total screen area.
 
@@ -54,11 +54,11 @@ function openWindow(left, top, width, height, url) {
   const windowFeatures = `left=${left},top=${top},width=${width},height=${height}`;
   const windowRef = window.open(
     url,
-    Math.random().toString(), // a target is needed for it to open as a separate window rather than a tab
+    "_blank", // needed for it to open in a new window
     windowFeatures,
   );
 
-  // Store a reference to the window in the windowRefs array
+  // Store a reference to the window in the windowRefs array for later use
   windowRefs.push(windowRef);
 }
 ```

files/en-us/web/api/screendetailed/left/index.md

@@ -15,19 +15,32 @@ The **`left`** read-only property of the
 
 This is equal to the true left-hand edge, ignoring any OS UI element drawn at the left of the screen. Windows cannot be placed in those areas; to get the left-hand coordinate of the screen area that windows can be placed in, use {{domxref("ScreenDetailed.availLeft")}}.
 
+> **Note:** In Firefox, a non-standard implementation of the `left` property is available on the `Screen` interface, and represents the x-coordinate (left-hand edge) of the _current_ screen's area (i.e. the screen containing the browser window the code is being run in). See the [Non-standard example](#non-standard_example) below for usage details, and see the [`Screen`](/en-US/docs/Web/API/Screen#browser_compatibility) reference page for browser support information relating to the non-standard implementation.
+
 ## Value
 
 A number.
 
 ## Examples
 
+### Window Management API example
+
 ```js
+// Available in browsers that support the Window Management API
 const screenDetails = await window.getScreenDetails();
 
 // Return the absolute left value of the first screen
 const screen1Left = screenDetails.screens[0].left;
 ```
 
+### Non-standard example
+
+```js
+// Available in Firefox
+// Return the absolute left value of the current screen
+const screenLeft = window.screen.left;
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/screendetailed/top/index.md

@@ -15,19 +15,32 @@ The **`top`** read-only property of the
 
 This is equal to the true top edge, ignoring any OS UI element drawn at the top of the screen. Windows cannot be placed in those areas; to get the top coordinate of the screen area that windows can be placed in, use {{domxref("ScreenDetailed.availTop")}}.
 
+> **Note:** In Firefox, a non-standard implementation of the `top` property is available on the `Screen` interface, and represents the y-coordinate (top edge) of the _current_ screen's area (i.e. the screen containing the browser window the code is being run in). See the [Non-standard example](#non-standard_example) below for usage details, and see the [`Screen`](/en-US/docs/Web/API/Screen#browser_compatibility) reference page for browser support information relating to the non-standard implementation.
+
 ## Value
 
 A number.
 
 ## Examples
 
+### Window Management API example
+
 ```js
+// Available in browsers that support the Window Management API
 const screenDetails = await window.getScreenDetails();
 
 // Return the absolute top value of the first screen
 const screen1Top = screenDetails.screens[0].top;
 ```
 
+### Non-standard example
+
+```js
+// Available in Firefox
+// Return the absolute top value of the current screen
+const screenTop = window.screen.top;
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/screendetails/currentscreen/index.md

@@ -23,39 +23,19 @@ A {{domxref("ScreenDetailed")}} object.
 // Utility function for opening new windows
 function openWindow(left, top, width, height, url) {
   const windowFeatures = `left=${left},top=${top},width=${width},height=${height}`;
-  const windowRef = window.open(
-    url,
-    Math.random().toString(), // a target is needed for it to open as a separate window rather than a tab
-    windowFeatures,
-  );
-
-  // Store a reference to the window in a windowRefs array
-  windowRefs.push(windowRef);
+  return window.open(url, "_blank", windowFeatures);
 }
 
-// Constants to represent the width and height of the Chrome UI when calculating the window size to open
-const WINDOW_CHROME_Y = 51;
-const WINDOW_CHROME_X = 1;
-
-const screenDetails = await window.getScreenDetails();
-
-// Return the current screen
-const curScreen = screenDetails.currentScreen;
-
-// Windows will be a third the width and the full height of the current screen
-let windowWidth = Math.floor((curScreen.availWidth - 3 * WINDOW_CHROME_X) / 3);
-let windowHeight = Math.floor(curScreen.availHeight - WINDOW_CHROME_Y);
-
-// Open the reference windows in thirds across the entire height of the current screen
-openWindow(
-  curScreen.availLeft,
-  curScreen.availTop,
-  windowWidth,
-  windowHeight,
-  sites[1].url,
+// Open a new window that fills the available area of the current screen.
+const currentScreen = (await window.getScreenDetails()).currentScreen;
+console.log(`Opening a window to fill screen ${currentScreen.label}`);
+const windowRef = openWindow(
+  currentScreen.availLeft,
+  currentScreen.availTop,
+  currentScreen.availWidth,
+  currentScreen.availHeight,
+  url,
 );
-
-// ...
 ```
 
 ## Specifications