DO NOT MERGE: Technical review for Window Management API docs #28851

chrisdavidmills · 2023-08-30T16:05:33Z

Note: This technical review is now completed and approved. For the follow-on editorial review, see #29719

Description

The Window Management API was implemented in Chrome 100 (see ChromeStatus entry); this PR provides docs for it.

See my research doc for complete details of the items that have been added.

Motivation

Additional details

Also see:

Associated BCD additions
Associated example addition to dom-examples

Related issues and pull requests

github-actions · 2023-08-30T16:07:36Z

Preview URLs (30 pages)

Flaws (9)

Note! 29 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/Window
Title: Window
Flaw count: 9

macros:
- /en-US/docs/Web/API/Window/setResizable does not exist
- /en-US/docs/Web/API/Window/animationcancel_event redirects to /en-US/docs/Web/API/Element/animationcancel_event
- /en-US/docs/Web/API/Window/animationend_event redirects to /en-US/docs/Web/API/Element/animationend_event
- /en-US/docs/Web/API/Window/animationiteration_event redirects to /en-US/docs/Web/API/Element/animationiteration_event
- /en-US/docs/Web/API/Window/animationstart_event redirects to /en-US/docs/Web/API/Element/animationstart_event
- and 4 more flaws omitted

External URLs (8)

URL: /en-US/docs/Web/API/ScreenDetails
Title: ScreenDetails

https://mdn.github.io/dom-examples/window-management-api/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Window_Management_API
Title: Window Management API

https://github.com/michaelwasserman/window-placement-demo (1 time) (Note! This may be a new URL 👀)
https://glitch.com/edit/ (1 time) (Note! This may be a new URL 👀)
https://mdn.github.io/dom-examples/window-management-api/ (1 time) (Note! This may be a new URL 👀)
https://michaelwasserman.github.io/window-placement-demo/ (1 time) (Note! This may be a new URL 👀)
https://window-placement.glitch.me/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/ScreenDetailed
Title: ScreenDetailed

https://mdn.github.io/dom-examples/window-management-api/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Window/getScreenDetails
Title: Window: getScreenDetails() method

https://mdn.github.io/dom-examples/window-management-api/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-10-19 07:06:53)

chrisdavidmills · 2023-09-26T12:12:43Z

@michaelwasserman hi there Michael. Please can you give me a technical review for these docs? The best place to start is #28851 (comment), which provides live previews of all the new/updated pages.

Sorry for the out-of-the-blue nature of this request. @tomayac said you would be the best person to ask ;-)

michaelwasserman · 2023-09-28T21:18:05Z

This is awesome, thank you! I started a detailed review, but can I ask for your patience until the week of October 9th?

chrisdavidmills · 2023-09-29T08:40:21Z

This is awesome, thank you! I started a detailed review, but can I ask for your patience until the week of October 9th?

@michaelwasserman Yup, w/c October 9th is absolutely fine.

michaelwasserman

This is AMAZING, thank you very much! I left some comments that I hope are helpful, and I'm happy to circle back with another look or discussion as appropriate.

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

michaelwasserman · 2023-10-12T22:53:22Z

files/en-us/_redirects.txt

@@ -2214,17 +2214,17 @@
 /en-US/docs/DOM/window.restore	/en-US/docs/Web/API/Window/moveTo
 /en-US/docs/DOM/window.screen	/en-US/docs/Web/API/Window/screen
 /en-US/docs/DOM/window.screen.availHeight	/en-US/docs/Web/API/Screen/availHeight
-/en-US/docs/DOM/window.screen.availLeft	/en-US/docs/Web/API/Screen/availLeft
-/en-US/docs/DOM/window.screen.availTop	/en-US/docs/Web/API/Screen/availTop
+/en-US/docs/DOM/window.screen.availLeft	/en-US/docs/Web/API/ScreenDetailed/availLeft


I wouldn't redirect folks looking for window.screen.availLeft (etc.) to the ScreenDetailed definition; they should continue to see existing https://developer.mozilla.org/en-US/docs/Web/API/Screen/availLeft (etc.) docs about the pre-existing non-standard properties defined on the Screen interface object window.screen. Right?

Hrm, this is a difficult situation to decide what is best. I do see your point, but at the same time, I feel that it is good to document the standardized version over the non-standard version in such cases. Plus, it is good to document features in one place rather than two otherwise you run the risk of reader confusion and maintenance difficulties.

I have thought about this a bit, and come to the following executive decision:

I am going to keep both sets of compat data for the affected properties. To represent both stories in the compat data in one place is too confusing and tricky, and will confuse more than it helps. (I tried to do so yesterday for quite a while, and just gave up in the end!)

I am keep the documentation for the affected properties in one place — hanging off ScreenDetailed.

I will add a note and a section to each of these pages to make the non-standard version support situation clear.

I will add a section to the main Screen page listing the non-standard versions and pointing to where they are documented.

Let me know what you think of these changes (in the next commit).

files/en-us/_wikihistory.json

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

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

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

michaelwasserman · 2023-10-14T00:03:35Z

One more comment: The API isn't currently supported on Chrome mobile, so "Browser compatibility" sections might need updating.

chrisdavidmills · 2023-10-16T16:28:38Z

One more comment: The API isn't currently supported on Chrome mobile, so "Browser compatibility" sections might need updating.

@michaelwasserman oops! I've actually started responding to your review by fixing this one; see mdn/browser-compat-data#20967. Thanks!

michaelwasserman

lgtm, with some hopefully helpful comments. Thank you very much!!!

michaelwasserman · 2023-10-18T00:07:07Z

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.


Standardized may imply stronger meaning than the reality? Window Management is "on the standards track". FWIW, an API goal would be to standardize the properties on Screen, then ScreenDetailed would just inherit those.

I see what you mean here. I have updated the wording to the following:

The following properties are specified as part of the Window Management API, which makes them available on the {{domxref("ScreenDetailed")}} interface; this is where we have chosen to document them. However, non-standard versions of these properties are available on the Screen interface in browsers that don't support that API. See this page's Browser compatibility table for details of the non-standard support.

michaelwasserman · 2023-10-18T00:16:43Z

files/en-us/web/api/window/moveto/index.md

@@ -15,8 +15,6 @@ interface moves the current window to the specified coordinates.
 > contrast, {{domxref("window.moveBy()")}} moves the window relative to its current
 > location.

-> **Note:** On devices with multiple displays, `moveTo()` positions windows relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin).


FWIW, these notes did seem somewhat helpful, if difficult to qualify with compat data.
Perhaps leaving them in, specific to Chromium based browsers would be helpful? Also, optionally noting user agents might clamp requested coordinates to the current/opener display (depending on window-management permission in Chromium based browser), etc.

See above. I think I'm going to leave the clamping behavior for now, and perhaps consider it at a later date.

chrisdavidmills · 2023-10-18T16:35:54Z

Thanks for the 2nd round of comments, @michaelwasserman. I've fixed those up now. Let me know if there are any other changes you'd like to see.

michaelwasserman

lgtm, thank you very much! (I don't have rights to "Approve")

This is fantastic documentation for the Window Management API, and a great step forward documenting the associated non-standard legacy API surfaces and implementation differences. This will be a great resources for web developers implementing multi-window and multi-screen functionality.

chrisdavidmills · 2023-10-19T07:03:49Z

lgtm, thank you very much! (I don't have rights to "Approve")

This is fantastic documentation for the Window Management API, and a great step forward documenting the associated non-standard legacy API surfaces and implementation differences. This will be a great resources for web developers implementing multi-window and multi-screen functionality.

@michaelwasserman wonderful, thank you! I have enjoyed working with you on this Mike; give me a shout in future if/when you work on other items that you'd like to see documented on MDN.

OK, so you've given the official engineering approval. Next we are going to try something new — I'm going to open a new PR based on this same branch so that we can keep the corresponding editorial review of this work separate, to try to keeps things a bit more clean (as these PRs can get really noisy). Just mentioning it so that you know what is going on.

chrisdavidmills · 2023-10-19T07:15:50Z

I think I need to close this one so I can open another.

Add docs for the Window Management API

198e6fd

chrisdavidmills requested review from a team as code owners August 30, 2023 16:05

chrisdavidmills requested review from wbamberg and bsmth and removed request for a team August 30, 2023 16:05

chrisdavidmills marked this pull request as draft August 30, 2023 16:05

github-actions bot added the Content:WebAPI Web API docs label Aug 30, 2023

Adding rest of pages for the API

f702ac1

github-actions bot added the Content:HTTP HTTP docs label Sep 4, 2023

Adding information about the multi-screen origin

6321a5e

chrisdavidmills marked this pull request as ready for review September 5, 2023 09:03

chrisdavidmills requested review from a team as code owners September 5, 2023 09:03

chrisdavidmills requested review from Elchi3 and removed request for a team September 5, 2023 09:03

chrisdavidmills added 2 commits September 5, 2023 10:04

Merge branch 'main' into window-management-api

cdaefab

Merge branch 'main' into window-management-api

aef485e

Merge branch 'main' into window-management-api

1a84d53

michaelwasserman reviewed Oct 14, 2023

View reviewed changes

Merge branch 'main' into window-management-api

abc63d6

chrisdavidmills mentioned this pull request Oct 17, 2023

Include detailed information about scaling on window.devicePixelRatio reference page #29682

Open

Making fixes for michaelwasserman comments

9193823

Merge branch 'main' into window-management-api

986f5c3

chrisdavidmills requested a review from michaelwasserman October 17, 2023 14:07

michaelwasserman reviewed Oct 18, 2023

View reviewed changes

chrisdavidmills added 2 commits October 18, 2023 17:30

Fixes for 2nd round of michaelwasserman comments

f58e40d

Merge branch 'main' into window-management-api

aaa6742

chrisdavidmills requested a review from michaelwasserman October 18, 2023 16:35

michaelwasserman reviewed Oct 18, 2023

View reviewed changes

Merge branch 'main' into window-management-api

d7b8d00

chrisdavidmills closed this Oct 19, 2023

chrisdavidmills mentioned this pull request Oct 19, 2023

Editorial review for Window Management API docs #29719

Merged

chrisdavidmills changed the title ~~Add docs for the Window Management API~~ DO NOT MERGE: Technical review for the Window Management API Oct 19, 2023

chrisdavidmills changed the title ~~DO NOT MERGE: Technical review for the Window Management API~~ DO NOT MERGE: Technical review for Window Management API docs Oct 19, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DO NOT MERGE: Technical review for Window Management API docs #28851

DO NOT MERGE: Technical review for Window Management API docs #28851

chrisdavidmills commented Aug 30, 2023 •

edited

Loading

github-actions bot commented Aug 30, 2023 •

edited

Loading

chrisdavidmills commented Sep 26, 2023

michaelwasserman commented Sep 28, 2023

chrisdavidmills commented Sep 29, 2023

michaelwasserman left a comment

michaelwasserman Oct 12, 2023

chrisdavidmills Oct 17, 2023 •

edited

Loading

michaelwasserman commented Oct 14, 2023

chrisdavidmills commented Oct 16, 2023

michaelwasserman left a comment

michaelwasserman Oct 18, 2023

chrisdavidmills Oct 18, 2023

michaelwasserman Oct 18, 2023

chrisdavidmills Oct 18, 2023

chrisdavidmills commented Oct 18, 2023

michaelwasserman left a comment

chrisdavidmills commented Oct 19, 2023

chrisdavidmills commented Oct 19, 2023

DO NOT MERGE: Technical review for Window Management API docs #28851

DO NOT MERGE: Technical review for Window Management API docs #28851

Conversation

chrisdavidmills commented Aug 30, 2023 • edited Loading

Description

Motivation

Additional details

Related issues and pull requests

github-actions bot commented Aug 30, 2023 • edited Loading

chrisdavidmills commented Sep 26, 2023

michaelwasserman commented Sep 28, 2023

chrisdavidmills commented Sep 29, 2023

michaelwasserman left a comment

Choose a reason for hiding this comment

michaelwasserman Oct 12, 2023

Choose a reason for hiding this comment

chrisdavidmills Oct 17, 2023 • edited Loading

Choose a reason for hiding this comment

michaelwasserman commented Oct 14, 2023

chrisdavidmills commented Oct 16, 2023

michaelwasserman left a comment

Choose a reason for hiding this comment

michaelwasserman Oct 18, 2023

Choose a reason for hiding this comment

chrisdavidmills Oct 18, 2023

Choose a reason for hiding this comment

michaelwasserman Oct 18, 2023

Choose a reason for hiding this comment

chrisdavidmills Oct 18, 2023

Choose a reason for hiding this comment

chrisdavidmills commented Oct 18, 2023

michaelwasserman left a comment

Choose a reason for hiding this comment

chrisdavidmills commented Oct 19, 2023

chrisdavidmills commented Oct 19, 2023

chrisdavidmills commented Aug 30, 2023 •

edited

Loading

github-actions bot commented Aug 30, 2023 •

edited

Loading

chrisdavidmills Oct 17, 2023 •

edited

Loading