Shadow DOM and requestPointerLock()

[hayatoito]

Title: [Shadow]: How should Element.requestPointerLock() work in shadow DOM? (bugzilla: 26934)

Migrated from: https://www.w3.org/Bugs/Public/show_bug.cgi?id=26934

---

comment: 0
comment_url: https://www.w3.org/Bugs/Public/show_bug.cgi?id=26934#c0
Olli Pettay wrote on 2014-09-29 23:47:53 +0000.

Currently requestPointerLock requires element to be in Document, but Chromium
does let one to lock pointer to a shadow dom element too.

---

comment: 1
comment_url: https://www.w3.org/Bugs/Public/show_bug.cgi?id=26934#c1
** wrote on 2014-09-30 15:38:41 +0000.

There's nothing fundamentally wrong with pointer lock targeting any element. Specifying the element must be in the document easily handles any kind of navigation concerns (where lock must be released) and dismiss any open ended questions about where events are headed if elements aren't in the document.

Here are the relevant sections of Pointer Lock:

"""
5.1 Methods

requestPointerLock

...

Pointer lock must succeed only if the target is in the active document of a browsing context which is (or has an ancestor browsing context which is) in focus by a window which is in focus by the operating system's window manager.

...

8 Requirements

Pointer lock must be exited if the target is removed from its document, or the user agent, window, or tab loses focus. Moving focus between elements of active documents, including between browsing contexts, does not exit pointer lock. E.g. using the keyboard to move focus between contents of frames or iframes will not exit.
"""

And here is a draft of a change to add shadow tree/host to the sections:

"""
5.1 Methods

requestPointerLock

...

Pointer lock must succeed only if the target is in the active document (or a shadow tree of a shadow host in the active document) of a browsing context which is (or has an ancestor browsing context which is) in focus by a window which is in focus by the operating system's window manager.

...

8 Requirements

Pointer lock must be exited if any of the follow occur:

• The target is removed from its document.
• The target is removed from its shadow tree.
• The user agent, window, or tab loses focus.
  Moving focus between elements of active documents, including between browsing contexts, does not exit pointer lock. E.g. using the keyboard to move focus between contents of frames or iframes will not exit.
  """

Review & comments please.

---

comment: 2
comment_url: https://www.w3.org/Bugs/Public/show_bug.cgi?id=26934#c2
Olli Pettay wrote on 2014-09-30 15:49:09 +0000.

5.1 Methods

requestPointerLock

...

Pointer lock must succeed only if the target is in the active document (or a
shadow tree of a shadow host in the active document)
We probably don't want elements in older shadow trees which aren't projected to newer shadow trees to
be able to lock the pointer.

[annevk]

@scheib, thoughts? See #180 for my thoughts on what to do for Fullscreen.

[scheib]

I don't know yet.

I'm not currently sufficiently familiar with Shadow DOM, and in 15 minutes could not understand open/closed trees, and thus do not understand the discussion in #180 for Fullscreen. I also don't fully understand andyearnshaw's fullscreen usecase.

From my simplistic understanding, Pointer Lock should work for any node in a tree that can eventually (even through shadow DOM boundaries) reach the root document node of a frame.

Permission should be controlled by a single origin.

Lock should be exited if the node is no longer in the tree (as above), or navigation, or loss of document focus.

Generally, if a shadow node has lock and there's a need to disambiguate that element, the shadowRoot.fullscreenElement concept seems to be reasonable, but I don't really understand it yet.

I can contribute more to this discussion after either finding more time to learn Shadow DOM or by answering more specific questions Shadow DOM folk have.

[annevk]

@scheib the principle we try to follow is that the "light tree" cannot know about the existence of the "shadow tree". (There's a couple of exceptions to that rule, but not for normal APIs such as Fullscreen and Pointer Lock, most likely. That's why document.fullscreenElement would be null when an element inside one of its shadow trees is fullscreen.)

Looking over https://w3c.github.io/pointerlock/ I guess the additional complication for Pointer Lock beyond what Fullscreen has is event retargeting and what that means for movementX/Y.

[scheib]

OK, so the goal is that when a shadow node acquires lock the light tree should be ignorant.

Then I would suggest

• Relocking without requiring a user gesture should only work from within the same tree. See 5.1 with text: "If a user has exited pointer lock via the default unlock user gesture, or pointer lock has not previously been entered for this document...". That logic is intended for script code to exit and re-enter lock state - but it doesn't make sense for that logic to cross a shadow tree boundary.
• When locked, no mouse event of any kind should be dispatched, or bubbled, to the light DOM.
• When locked to a light or shadow tree A a subsequent lock to a node in a different light or shadow tree B should be blocked, similar to text in requestPointerLock

If any element in another document is already locked the request must fail and a pointerlockerror event be sent.

I don't fully understand the shadow tree document structure. Does each tree have a document, or is the document a mix of trees? Presuming the later, these are needed:

• shadowRoot.pointerlockElement so that the shadow node can use the element, while light DOM is not affected.
• shadowRoot.onpointerlockchange and shadowRoot.onpointerlockerror would also be needed to be hidden in shadowRoot
• shadowRoot.exitPointerLock should only work for a lock in the currently locked tree.

I don't think changes are needed for:

• movementX/Y. So long as no events are reached by the light tree there will be no opportunity to read those values.
• light tree 'enabling' the feature, similar to iframe (see 5.1 requestPointerLock active sandboxing flag)

[annevk]

Thank you, that seems pretty reasonable to me. There's no rush for Pointer Lock to move first here. I'll ping this thread when some other features have started accounting for shadow trees.

[hayatoito]

It looks okay, however, DocumentOrShadowRoot is the place where pointerlockElement, onpointerlockchange, onpointerlockerror, exitPointerLock should be defined.

You can use this mixin, instead of Document, in the Pointer Lock spec.

[hayatoito]

I have merged #180 into this issue.
@scheib , could you update https://w3c.github.io/pointerlock/ ?

If you need help, I think we are happy to help you.

[TakayoshiKochi]

Now this is detached from #180 again, but it is quite similar in API surface.
If I apply the same (#180) to this, the following differs from what @scheib and @HAYATO said in the above:

• when an element in a shadow tree acquires pointer lock, document.pointerLockElement can point to its shadow host, and its shadowRoot.pointerLockElement points to the pointer locked element. (or if the element is further down descendant shadows, points to a shadow host, recursively)
• pointerlockchange / pointerlockerror events are dispatched on document, not on shadow roots (maybe in the future, after Shadow DOM v1)

@scheib does this look good to you?
If anything is unclear about Shadow DOM, please let me know. From reading your comments above, your understanding of Shadow DOM looks quite good.

[scheib]

Thank you, I agree with these, as we discussed in person.

[TakayoshiKochi]

The spec working draft is updated to include the conclusion here.

@hayatoito could you close this?