From c995112a140b4573b887caf3e3ae98be04828f28 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Philip=20J=C3=A4genstedt?= <philip@foolip.org>
Date: Wed, 5 Oct 2022 14:30:42 +0200
Subject: [PATCH] Add a context parameter for browsingContext.create (#153)

This is based on @jgraham's suggestion:
https://github.com/w3c/webdriver-bidi/pull/133#discussion_r757432132

Co-authored-by: Julian Descottes <jdescottes@mozilla.com>
Co-authored-by: Maksim Sadym <69349599+sadym-chromium@users.noreply.github.com>
---
 index.bs | 49 +++++++++++++++++++++++++++++++++++--------------
 1 file changed, 35 insertions(+), 14 deletions(-)

diff --git a/index.bs b/index.bs
index 3d453f1f..112de309 100644
--- a/index.bs
+++ b/index.bs
@@ -2876,7 +2876,8 @@ The <dfn export for=commands>browsingContext.create</dfn> command creates a new
       BrowsingContextCreateType = "tab" / "window"
 
       BrowsingContextCreateParameters = {
-        type: BrowsingContextCreateType
+        type: BrowsingContextCreateType,
+        ?referenceContext: BrowsingContext
       }
       </pre>
    </dd>
@@ -2896,6 +2897,19 @@ The [=remote end steps=] with |command parameters| are:
   1. Let |type| be the value of the <code>type</code> field of
      |command parameters|.
 
+  1. Let |reference context id| be the value of the <code>referenceContext</code>
+     field of |command parameters|, if present, or null otherwise.
+
+  1. If |reference context id| is not null, let |reference context| be the
+     result of [=trying=] to [=get a browsing context=] with
+     |reference context id|. Otherwise let |reference context| be null.
+
+ 1. If |reference context| is not null and is not a [=top-level browsing context=],
+    return [=error=] with [=error code=] [=invalid argument=].
+
+  1. If the implementation is unable to create a new browsing context for any
+     reason then return [=error=] with [=error code=] [=unsupported operation=].
+
   <!-- This is based on step 5 of https://w3c.github.io/webdriver/#new-window,
        but without using the "current browsing context" concept. -->
   1. Create a new [=top-level browsing context=] by running the [=window open
@@ -2903,19 +2917,26 @@ The [=remote end steps=] with |command parameters| are:
      <var ignore>target</var> set to the empty string, and
      <var ignore>features</var> set to "<code>noopener</code>". This must be
      done without invoking the [=/focusing steps=] for the created browsing
-     context. If |type| is "<code>tab</code>", and the implementation supports
-     multiple browsing contexts in the same OS window, the new browsing context
-     should share an OS window with any other [=top-level browsing context=]. If
-     |type| is "<code>window</code>", and the implementation supports multiple
-     browsing contexts in separate OS windows, the created browsing context
-     should be in a new OS window. In all other cases the details of how the
-     browsing context is presented to the user are implementation defined.
-
-     Issue: HTML's [=window open steps=] depend on the "entry global object"
-     and WebDriver's <a href="https://w3c.github.io/webdriver/#new-window">New
-     Window</a> command depends on the "current browsing context". Given that we
-     don't have any such implicit context here, what OS window should new tabs
-     be opened in?
+     context. Which OS window the new [=/browsing context=] is created in
+     depends on |type| and |reference context|:
+
+     * If |type| is "<code>tab</code>" and the implementation supports
+       multiple browsing contexts in the same OS window:
+
+       * The new browsing context should reuse an existing OS window, if any.
+
+       * If |reference context| is not null, the new browsing context should
+         reuse the window containing |reference context|, if any. If the
+         top-level browsing contexts inside an OS window have a definite ordering,
+         the new browsing context should be immediately after
+         |reference context|'s [=top-level browsing context=] in that ordering.
+
+     * If |type| is "<code>window</code>", and the implementation supports
+       multiple browsing contexts in separate OS windows, the created browsing
+       context should be in a new OS window.
+
+     * Otherwise, the details of how the browsing context is presented to the
+       user are implementation defined.
 
   1. Let |context id| be the [=browsing context id=] of the newly created
      [=/browsing context=].