From 5428c8b3509d4550cd9d00ba4ae3f869b7ec044a Mon Sep 17 00:00:00 2001 From: Jim Evans Date: Wed, 6 Jan 2021 12:41:54 -0500 Subject: [PATCH 1/5] Initial attempt at Shadow DOM spec prose --- index.html | 283 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 281 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 8bc767e4..81d20c7b 100644 --- a/index.html +++ b/index.html @@ -818,6 +818,12 @@

Endpoints

Get Active Element + + GET + /session/{session id}/element/{element id}/shadow + Get Element Shadow Root + + POST /session/{session id}/element @@ -842,6 +848,18 @@

Endpoints

Find Elements From Element + + POST + /session/{session id}/shadow/{shadow id}/element + Find Element From Shadow Root + + + + POST + /session/{session id}/shadow/{shadow id}/elements + Find Elements From Shadow Root + + GET /session/{session id}/element/{element id}/selected @@ -1215,6 +1233,13 @@

Errors

could not be satisfied because the window could not be found. + + no such shadow root + 404 + no such shadow root + The element does not have a shadow root. + + script timeout error 500 @@ -1237,6 +1262,14 @@

Errors

the referenced element is no longer attached to the DOM. + + detached shadow root + 404 + detached shadow root + A command failed because + the referenced shadow root is no longer attached to the DOM. + + timeout 500 @@ -4314,6 +4347,103 @@

Interactability

+
+

Shadow Roots

+

A shadow root + is an abstraction used to identify a shadow root + when it is transported via the protocol, + between remote- and local ends. + +

The shadow root identifier is the string constant + "shadow-6066-11e4-a52e-4f735466cecf". + +

Each shadow root has an associated shadow root + reference that uniquely identifies the element across + all browsing contexts. The shadow root reference for + every shadow root representing the same shadow root must be the + same. It must be a string, and should be the result of generating + a UUID. + +

An ECMAScript Object represents a shadow root + if it has a shadow root identifier own property. + +

Each browsing context has an associated list of + known shadow roots. + When the browsing context is discarded, + the list of known shadow roots is discarded along with it. + +

To get a known shadow root with + argument reference, run the following steps: + +

    +
  1. Let shadow be the item in the current browsing + context’s list of known shadow roots for which the shadow + root reference is equal to reference, if such a + shadow root exists. Otherwise return error with error + code no such element. +
  2. If shadow is detached, return + error with error code + detached shadow root. +
  3. Return success with shadow. +
+ +

To get a known connected shadow root with + argument reference, run the following steps: +

    +
  1. Let shadow be the result of trying to get + a known shadow root with argument reference. +
  2. If shadow is detached + return error with error code detached shadow root. +
  3. Return success with shadow. +
+ +

To create a shadow root reference + for a shadow root: + +

    +

  1. For each known shadow root + of the current browsing context’s list of known shadow roots: + +

      +

    1. If known shadow root equals shadow root, + return success with known shadow root’s shadow root reference. +

    + +

  2. Add shadow to + the list of known shadow roots of the current browsing context. + +

  3. Return success with the + shadow’s shadow root reference. +

+ +

The JSON serialization of a shadow root + is a JSON Object where the shadow root identifier key + is mapped to the shadow root’s shadow root reference. + +

When required to deserialize a shadow root + by a JSON Object object that represents a shadow root: + +

    +

  1. If object has no own property shadow root identifier, + return error with error code invalid argument. + +

  2. Let reference be the result of + getting + the shadow root identifier property + from object. + +

  3. Let shadow be the result + of trying to get a known shadow root + with argument reference. + +

  4. Return success with data shadow. +

+ +

An shadow root is detached + if its node document is not the active document + or if the element node referred to as its document fragment host + is stale. +

Retrieval

@@ -4321,7 +4451,9 @@

Retrieval

The Find Element, Find Elements, Find Element From Element, - and Find Elements From Element commands + Find Elements From Element, + Find Element From Shadow Root, + and Find Elements From Shadow Root commands allow lookup of individual elements and collections of elements. Element retrieval searches are performed using pre-order traversal of the document’s nodes @@ -4772,6 +4904,101 @@

Find Elements From Element

+
+

Find Element From Shadow Root

+ + + + + + + + + + +
HTTP MethodURI Template
POST/session/{session id}/shadow/{shadow id}/element
+ +

The remote end steps are: + +

    +

  1. Let location strategy be the result + of getting a property called "using". + +

  2. If location strategy is not present as a keyword in the + table of location strategies, return error with + error code invalid argument. + +

  3. Let selector be the result + of getting a property called "value". + +

  4. If selector is undefined, + return error with error code invalid argument. + +

  5. If the current browsing context is no longer + open, return error with error code no such + window. + +

  6. Handle any user prompts and return its value if it is an error. + +

  7. Let start node be the result + of trying to get a known connected shadow root + with url variable shadow id. + +

  8. Let result be the value of trying to Find with + start node, location strategy, + and selector. + +

  9. If result is empty, return error + with error code no such shadow root. Otherwise, return the + first element of result. +

+
+ +
+

Find Elements From Shadow Root

+ + + + + + + + + + +
HTTP MethodURI Template
POST/session/{session id}/shadow/{shadow id}/elements
+ +

The remote end steps are: + +

    +

  1. Let location strategy be the result + of getting a property called "using". + +

  2. If location strategy is not present as a keyword in the + table of location strategies, return error with + error code invalid argument. + +

  3. Let selector be the result + of getting a property called "value". + +

  4. If selector is undefined, + return error with error code invalid argument. + +

  5. If the current browsing context is no longer + open, return error with error code no such + window. + +

  6. Handle any user prompts and return its value if it is an error. + +

  7. Let start node be the result + of trying to get a known connected shadow root + with url variable shadow id. + +

  8. Return the result of trying to Find with + start node, location strategy, and selector. +
+
+

Get Active Element

@@ -4804,6 +5031,57 @@

Get Active Element

Otherwise, return error with error code no such element.

+ +
+

Get Element Shadow Root

+ + + + + + + + + + +
HTTP MethodURI Template
GET/session/{session id}/element/shadow
+ +

The remote end steps are: + +

    +

  1. If the current browsing context is no longer + open, return error with error code no such + window. + +

  2. Handle any user prompts and return its value if it is an error. + +

  3. Let element be the result + of trying to get a known connected element + with url variable element id. + +

  4. Let shadow root be the result of getting an + own property named "shadowRoot" from element. + +

  5. If shadow root is undefined, return error + with error code no such shadow root. + +

  6. Let shadow root node type be the result of + getting an own property named "nodeType" from + shadow root. + +

  7. If shadow root node type is undefined, or has + a value other than 11, return error with error code + no such shadow root. + +

  8. Let shadow host be the result of getting an + own property named "host" of shadow root. + +

  9. If shadow host is not undefined or null, return + create a shadow root reference. + +

    Otherwise, return error with error code no such shadow root. +

+
@@ -10346,6 +10624,7 @@

Index

  • Document element
  • Document
  • DOCUMENT_POSITION_DISCONNECTED (1) +
  • document fragment host
  • Document type
  • Document URL
  • Element @@ -10373,7 +10652,7 @@

    Index

    in the Document Object Model specification: [[DOM]] +

    The following terms are defined in the DOM Parsing and Serialization specification: [[DOM-PARSING]] From 15037d17b2278984a005abad924474fe9975a67e Mon Sep 17 00:00:00 2001 From: Jim Evans Date: Wed, 6 Jan 2021 12:52:43 -0500 Subject: [PATCH 2/5] Correcting inadvertent indent edit --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 81d20c7b..bd61daff 100644 --- a/index.html +++ b/index.html @@ -10652,7 +10652,7 @@

    Index

    in the Document Object Model specification: [[DOM]] +

    The following terms are defined in the DOM Parsing and Serialization specification: [[DOM-PARSING]] From d4b5c86508140b8387fee7f002daad3be93e74f8 Mon Sep 17 00:00:00 2001 From: Jim Evans Date: Sun, 10 Jan 2021 16:25:01 -0500 Subject: [PATCH 3/5] Correct URLs for Get Element Shadow Root command --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index bd61daff..9bef945c 100644 --- a/index.html +++ b/index.html @@ -820,7 +820,7 @@

    Endpoints

    GET - /session/{session id}/element/{element id}/shadow + /session/{session id}/element/{element id}/shadow Get Element Shadow Root @@ -5042,7 +5042,7 @@

    Get Element Shadow Root

    GET - /session/{session id}/element/shadow + /session/{session id}/element/{element id}/shadow From 6913957ad1ae2da613db5cf3d5358c685912e8a6 Mon Sep 17 00:00:00 2001 From: Jim Evans Date: Mon, 11 Jan 2021 07:51:12 -0500 Subject: [PATCH 4/5] Responding to first round of review comments --- index.html | 29 ++++++++++------------------- 1 file changed, 10 insertions(+), 19 deletions(-) diff --git a/index.html b/index.html index 9bef945c..775a9a4e 100644 --- a/index.html +++ b/index.html @@ -850,13 +850,13 @@

    Endpoints

    POST - /session/{session id}/shadow/{shadow id}/element + /session/{session id}/shadow/{shadow id}/element Find Element From Shadow Root POST - /session/{session id}/shadow/{shadow id}/elements + /session/{session id}/shadow/{shadow id}/elements Find Elements From Shadow Root @@ -4352,13 +4352,13 @@

    Shadow Roots

    A shadow root is an abstraction used to identify a shadow root when it is transported via the protocol, - between remote- and local ends. + between remote and local ends.

    The shadow root identifier is the string constant "shadow-6066-11e4-a52e-4f735466cecf".

    Each shadow root has an associated shadow root - reference that uniquely identifies the element across + reference that uniquely identifies the shadow root across all browsing contexts. The shadow root reference for every shadow root representing the same shadow root must be the same. It must be a string, and should be the result of generating @@ -4387,16 +4387,6 @@

    Shadow Roots

  • Return success with shadow. -

    To get a known connected shadow root with - argument reference, run the following steps: -

      -
    1. Let shadow be the result of trying to get - a known shadow root with argument reference. -
    2. If shadow is detached - return error with error code detached shadow root. -
    3. Return success with shadow. -
    -

    To create a shadow root reference for a shadow root: @@ -4439,7 +4429,7 @@

    Shadow Roots

  • Return success with data shadow. -

    An shadow root is detached +

    A shadow root is detached if its node document is not the active document or if the element node referred to as its document fragment host is stale. @@ -4941,7 +4931,7 @@

    Find Element From Shadow Root

  • Handle any user prompts and return its value if it is an error.

  • Let start node be the result - of trying to get a known connected shadow root + of trying to get a known shadow root with url variable shadow id.

  • Let result be the value of trying to Find with @@ -4991,7 +4981,7 @@

    Find Elements From Shadow Root

  • Handle any user prompts and return its value if it is an error.

  • Let start node be the result - of trying to get a known connected shadow root + of trying to get a known shadow root with url variable shadow id.

  • Return the result of trying to Find with @@ -5070,8 +5060,8 @@

    Get Element Shadow Root

    shadow root.

  • If shadow root node type is undefined, or has - a value other than 11, return error with error code - no such shadow root. + a value other than DOCUMENT_FRAGMENT_NODE, return error + with error code no such shadow root.

  • Let shadow host be the result of getting an own property named "host" of shadow root. @@ -10625,6 +10615,7 @@

    Index

  • Document
  • DOCUMENT_POSITION_DISCONNECTED (1)
  • document fragment host +
  • DOCUMENT_FRAGMENT_NODE
  • Document type
  • Document URL
  • Element From 3e40fe086dc0bdf5f45f46f2e770541921de42c2 Mon Sep 17 00:00:00 2001 From: Jim Evans Date: Mon, 11 Jan 2021 09:17:52 -0500 Subject: [PATCH 5/5] Addressing more review comments --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 775a9a4e..fc9a53f2 100644 --- a/index.html +++ b/index.html @@ -4387,7 +4387,7 @@

    Shadow Roots

  • Return success with shadow. -

    To create a shadow root reference +

    To create a shadow root reference for a shadow root:

      @@ -5067,7 +5067,7 @@

      Get Element Shadow Root

      own property named "host" of shadow root.

    1. If shadow host is not undefined or null, return - create a shadow root reference. + a new shadow root reference.

      Otherwise, return error with error code no such shadow root.