document.caretPositionFromPoint API in shadow DOM scenario

[siliu1]

こんにちは TAG-さん!

I'm requesting a TAG review of document.caretPositionFromPoint API in shadow DOM scenario.

The document.caretPositionFromPoint returns a CaretPosition which represents the caret position indicating current text insertion point. However, the current spec is vague about the behavior in shadow DOM scenario. The proposal attempts to specify the behavior in shadow DOM.

• Explainer¹ (minimally containing user needs and example code): explainer below[1]
• Specification URL: current spec: https://www.w3.org/TR/cssom-view-1/#dom-document-caretpositionfrompoint. Proposed spec change: [cssom-view] add shadowRoots parameter to caretPositionFromPoint API. w3c/csswg-drafts#10200
• Tests: None for shadow DOM scenario. For light DOM: https://github.com/web-platform-tests/wpt/blob/master/css/cssom/caretPositionFromPoint.html
• User research: N/A
• Security and Privacy self-review²: N/A as there are no additional security implications over existing API.
• GitHub repo (if you prefer feedback filed there): https://github.com/w3c/csswg-drafts/issues (cssom-view label)
• Primary contacts (and their relationship to the specification):
  • Siye Liu (@siliu1, Microsoft, implementor)
• Organization(s)/project(s) driving the specification: Microsoft
• Key pieces of existing multi-stakeholder or discussion of this specification: This has been discussed at CSSWG via [cssom-view] Specify document.caretPositionFromPoint in shadow DOM scenario w3c/csswg-drafts#9932
• External status/issue trackers for this specification (publicly visible, e.g. Chrome Status): https://chromestatus.com/feature/5201014343073792

Further details:

• I have reviewed the TAG's Web Platform Design Principles
• Relevant time constraints or deadlines: None
• The group where the work on this specification is currently being done: CSSWG
• The group where standardization of this work is intended to be done (if current group is a community group or other incubation venue): CSSWG
• Major unresolved issues with or opposition to this specification: We have not heard of opposition, the proposal has been discussed in CSSWG and came to an agreement.
• This work is being funded by: Microsoft

---

[1] document.caretPositionFromPoint in shadow DOM scenario explainer:

Use case/developer need

It's necessary for web developers to have a method to determine the caret position within shadow roots. This allows for indentifying node
and offset within the shadow root so that range/selection creation is possible in shadow root at specific point.

With the proposal, web developer can get caret position inside shadow root like:

var caret_position = document.caretPositionFromPoint(x, y, shadowRoot1);
// caret_position.offsetNode is inside shadowRoot1
// caret_position.offset is the offset within offsetNode
// caret_position.getClientRect() returns a DOMRect which would be the caret bounds in shadowRoot1.

Background

The document.caretPositionFromPoint API returns a
CaretPosition which represents the caret position indicating current
text insertion point. However, the current spec doesn't
specifically define if and how shadow DOM scenarios should be supported. We want to update the API and spec to support shadow DOM cases
in a well defined way.

Proposal

Similar to Selection.getComposedRanges API, We should
introduce another argument shadowRoots which is the list of shadow roots that the API can pierce into. The API will look like:

document.caretPositionFromPoint(double x, double y, ShadowRoot... shadowRoots)

the returned caret position will only be in the shadow root if it's provided in shadowRoots argument. Otherwise, the caret position will
be in the shadow host's parent at the offset of the shadow host.

The proposed change to the API maintains the boundary of closed shadow tree unless the shadow root is provided to the API.

Alternative considered

• Do not let this API pierce into shadow tree. Instead, put this API on DocumentOrShadowRoot.

The con to this approach is that the usage might be cumbersome to get a position inside nested shadow roots (need to call the API on each
level of shadow root).

---

[martinthomson]

@siliu1 have you reviewed the design principles?

[zcorpan]

* Primary contacts (and their relationship to the specification):
  
  * Siye Liu (@siliu1, Microsoft, implementor)
  * Simon Pieters (@zcorpan, Mozilla, spec author)

I reviewed the spec change, but did not write it.

[siliu1]

Updated description based on above feedbacks.