From fbcde28e7b8d5edd289b60f054454b9cbfbee057 Mon Sep 17 00:00:00 2001 From: Frank Liberato Date: Mon, 19 Aug 2024 16:51:46 +0000 Subject: [PATCH 1/5] started Conflicts: spec.bs --- spec.bs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec.bs b/spec.bs index b52c7e6..4a8513b 100644 --- a/spec.bs +++ b/spec.bs @@ -108,6 +108,7 @@ partial interface Window { interface DocumentPictureInPicture : EventTarget { [NewObject] Promise<Window> requestWindow( optional DocumentPictureInPictureOptions options = {}); + void ready(Window window); readonly attribute Window window; attribute EventHandler onenter; }; @@ -117,6 +118,7 @@ dictionary DocumentPictureInPictureOptions { [EnforceRange] unsigned long long height = 0; boolean disallowReturnToOpener = false; boolean preferInitialWindowPlacement = false; + boolean waitForReady = false; }; [Exposed=Window, SecureContext] From 77052de9313c654ccc13cbc4fdea28eca51c7f08 Mon Sep 17 00:00:00 2001 From: Frank Liberato Date: Tue, 20 Aug 2024 19:50:49 +0000 Subject: [PATCH 2/5] added spec --- spec.bs | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/spec.bs b/spec.bs index 4a8513b..06be0de 100644 --- a/spec.bs +++ b/spec.bs @@ -233,6 +233,25 @@ previous position or size of any previously closed |pip traversable| window. and is true, the user agent should not display UI affordances on the picture-in-picture window that allow the user to return to the opener window. +15. If |options|["{{DocumentPictureInPictureOptions/waitForReady}}"] exists + and is true, the user agent should not show the picture-in-picture + window immediately. Instead, it will wait until one of these becomes true: + 1. {{DocumentPictureInPicture/ready()}} is called, with the corresponding + window as its argument. + 2. The transient activation used in step 4 would time out. + Calls to {{DocumentPictureInPicture/ready()}} after the picture-in-picture window + is shown, after it is destroyed, will do nothing. + If |options|["{{DocumentPictureInPictureOptions/waitForReady}}"] does not exist + or is not true, then the picture-in-picture window will be shown immediately after + it is created. +

+The intention for automatically showing the window when the transient activation would +time out is to allow the site to delay showing the window approximately as long as it +could have waited to call {{DocumentPictureInPicture/requestWindow()}}. Allowing the +site to defer showing the window is intended to let it do initial setup of the window +for a smoother transition, but not to allow the site to postpone showing the window +any longer than it could without the option. +

For both video and document picture-in-picture, user agents often display a @@ -788,6 +807,18 @@ await documentPictureInPicture.requestWindow({ }); +## Defer showing the picture-in-picture window ## {#example-wait-for-ready} + +If the site would like to configure the picture-in-picture window contents +before showing the window, it may use the +{{DocumentPictureInPictureOptions/waitForReady}} option to do so. + +

+let pip = await documentPictureInPicture.requestWindow({ waitForReady: true });
+// Add things to pip.document here!
+documentPictureInPicture.ready(pip);
+
+ # Acknowledgments # {#acknowledgments} Many thanks to Frank Liberato, Mark Foltz, Klaus Weidner, François Beaufort, From 21db0d7d73ee8ef7300aad2531caa223b7c81ebe Mon Sep 17 00:00:00 2001 From: Frank Liberato Date: Tue, 20 Aug 2024 19:54:13 +0000 Subject: [PATCH 3/5] renamed to createHidden Conflicts: spec.bs --- spec.bs | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/spec.bs b/spec.bs index 06be0de..ff18cc8 100644 --- a/spec.bs +++ b/spec.bs @@ -108,7 +108,7 @@ partial interface Window { interface DocumentPictureInPicture : EventTarget { [NewObject] Promise<Window> requestWindow( optional DocumentPictureInPictureOptions options = {}); - void ready(Window window); + void show(Window window); readonly attribute Window window; attribute EventHandler onenter; }; @@ -118,7 +118,7 @@ dictionary DocumentPictureInPictureOptions { [EnforceRange] unsigned long long height = 0; boolean disallowReturnToOpener = false; boolean preferInitialWindowPlacement = false; - boolean waitForReady = false; + boolean createHidden = false; }; [Exposed=Window, SecureContext] @@ -233,15 +233,15 @@ previous position or size of any previously closed |pip traversable| window. and is true, the user agent should not display UI affordances on the picture-in-picture window that allow the user to return to the opener window. -15. If |options|["{{DocumentPictureInPictureOptions/waitForReady}}"] exists +15. If |options|["{{DocumentPictureInPictureOptions/createHidden}}"] exists and is true, the user agent should not show the picture-in-picture window immediately. Instead, it will wait until one of these becomes true: - 1. {{DocumentPictureInPicture/ready()}} is called, with the corresponding + 1. {{DocumentPictureInPicture/show()}} is called, with the corresponding window as its argument. 2. The transient activation used in step 4 would time out. - Calls to {{DocumentPictureInPicture/ready()}} after the picture-in-picture window + Calls to {{DocumentPictureInPicture/show()}} after the picture-in-picture window is shown, after it is destroyed, will do nothing. - If |options|["{{DocumentPictureInPictureOptions/waitForReady}}"] does not exist + If |options|["{{DocumentPictureInPictureOptions/createHidden}}"] does not exist or is not true, then the picture-in-picture window will be shown immediately after it is created.

@@ -807,16 +807,16 @@ await documentPictureInPicture.requestWindow({ }); -## Defer showing the picture-in-picture window ## {#example-wait-for-ready} +## Defer showing the picture-in-picture window ## {#example-create-hidden} If the site would like to configure the picture-in-picture window contents before showing the window, it may use the -{{DocumentPictureInPictureOptions/waitForReady}} option to do so. +{{DocumentPictureInPictureOptions/createHidden}} option to do so. 

-let pip = await documentPictureInPicture.requestWindow({ waitForReady: true });
+let pip = await documentPictureInPicture.requestWindow({ createHidden: true });
 // Add things to pip.document here!
-documentPictureInPicture.ready(pip);
+documentPictureInPicture.show(pip);
# Acknowledgments # {#acknowledgments} From 8d979abcf87f695936666c3c7c573588f2bca30f Mon Sep 17 00:00:00 2001 From: Frank Liberato Date: Tue, 20 Aug 2024 19:56:54 +0000 Subject: [PATCH 4/5] cleanup --- spec.bs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec.bs b/spec.bs index ff18cc8..c4c8879 100644 --- a/spec.bs +++ b/spec.bs @@ -240,7 +240,9 @@ previous position or size of any previously closed |pip traversable| window. window as its argument. 2. The transient activation used in step 4 would time out. Calls to {{DocumentPictureInPicture/show()}} after the picture-in-picture window - is shown, after it is destroyed, will do nothing. + is shown, or after it is closed, will do nothing. A call that provides a window argument + that was not returned by {{DocumentPictureInPicture/requestWindow()}} will throw a + "{{NotAllowedError}}" {{DOMException}}. If |options|["{{DocumentPictureInPictureOptions/createHidden}}"] does not exist or is not true, then the picture-in-picture window will be shown immediately after it is created. From e71090e4f7d143cb3148d1c599f2f854de5524ef Mon Sep 17 00:00:00 2001 From: Frank Liberato Date: Tue, 20 Aug 2024 21:35:37 +0000 Subject: [PATCH 5/5] made timeout chosen by UA --- spec.bs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/spec.bs b/spec.bs index c4c8879..5068fe6 100644 --- a/spec.bs +++ b/spec.bs @@ -235,10 +235,10 @@ previous position or size of any previously closed |pip traversable| window. opener window. 15. If |options|["{{DocumentPictureInPictureOptions/createHidden}}"] exists and is true, the user agent should not show the picture-in-picture - window immediately. Instead, it will wait until one of these becomes true: + window immediately. Instead, it will wait until either: 1. {{DocumentPictureInPicture/show()}} is called, with the corresponding window as its argument. - 2. The transient activation used in step 4 would time out. + 2. The UA shows the window automatically after some time has elapsed. Calls to {{DocumentPictureInPicture/show()}} after the picture-in-picture window is shown, or after it is closed, will do nothing. A call that provides a window argument that was not returned by {{DocumentPictureInPicture/requestWindow()}} will throw a @@ -247,12 +247,12 @@ previous position or size of any previously closed |pip traversable| window. or is not true, then the picture-in-picture window will be shown immediately after it is created.

-The intention for automatically showing the window when the transient activation would -time out is to allow the site to delay showing the window approximately as long as it -could have waited to call {{DocumentPictureInPicture/requestWindow()}}. Allowing the -site to defer showing the window is intended to let it do initial setup of the window -for a smoother transition, but not to allow the site to postpone showing the window -any longer than it could without the option. +The intention to automatically show the window after a timeout is to allow the UA to +prevent a site from waiting indefinitely to show a window. For example, a UA might +choose to use the remaining lifetime of the transient activation that allowed the call to +{{DocumentPictureInPicture/requestWindow()}} to succeed, so that the site cannot show +the window any later than it could by simply waiting to open the picture-in-picture +window. The UA is free to choose any timeout, including "forever".