search

w3ctag / design-reviews

W3C specs and API reviews
Creative Commons Zero v1.0 Universal
318 stars 55 forks source link

document.caretPositionFromPoint API in shadow DOM scenario #949

Closed siliu1 closed 1 week ago

siliu1 commented 2 months ago

こんにちは 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.

Further details:

[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

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 commented 1 month ago

@siliu1 have you reviewed the design principles?

zcorpan commented 1 month ago 
* 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 commented 1 month ago

Updated description based on above feedbacks.

LeaVerou commented 2 weeks ago

Hi there,

We looked at this during a breakout today.

First, the purpose of the explainer is not just to assist in TAG review, but to provide an overview of what the spec does, why it’s needed, and why it’s designed that way, for everyone. Including an explainer in the TAG review issue does not help with that.

Second, one of the most important sections of the explainer is user needs. Here there are none. Getting the caret position is not a use case, it’s a solution. Why do they need to get the caret position?

This is essential for evaluating the design. For example, if addressing the common use cases requires getting all shadow roots in a document and passing them to this function, the ergonomics are suboptimal, since the developer would have to query all elements, traverse them to see which ones have an open shadow root, then pass them to the function:

let shadowRoots = [];
for (let el of document.querySelectorAll("*")) {
    if (el.shadowRoot) shadowRoots.push(el.shadowRoot);
}
let pos = document.caretFromPoint(x, y, shadowRoots);

But if it’s not common to need to do it in such a sweeping manner, but more targeted to a few shadow roots, it may be acceptable to provide them explicitly. Without a good set of use cases, we simply cannot know.

The shadowRoots parameter does double duty here: it opts in to the new behavior AND provides the shadow roots the code knows about. Again, depending on the use cases, this could be ok, but if aggregation is often desired (fetching all open shadow roots under a container), it can get tedious. It may be worth exploring alternative designs where this is easily possible.

Do note that we advise against optional parameters being positional, and recommend a dictionary instead which both makes function calls self-explanatory and affords room for future expansion.

As an example, one possible design could be to make the parameter a dictionary with a shadowRoots option, which could take either an array of Node instances, or a Node (which would be treated the same as an array of one element). For non-ShadowRoot nodes, all open shadow roots within that container would be fetched. This means that shadowRoots: document addresses the use case of getting all open shadow roots with no further complication to the API, and closed shadow roots can still be provided like shadowRoots: [document, shadow1, shadow2, ...].

We also noticed that elementFromPoint() and elementsFromPoint() still only have x and y parameters. Modifying the signature of one but not the other breaks consistency and should be avoided.

siliu1 commented 1 week ago

Hi Lea,

Thank you for the review.

The latest spec of this API has been changed to take a dictionary with shadowRoots option: https://drafts.csswg.org/cssom-view/#ref-for-dom-document-caretpositionfrompoint.

Regarding the open shadow roots vs. closed shadow roots, there is an existing API Element.getHTML that takes a dictionary with a shadowRoots option for both open and closed shadow roots. I think it's better to make it consistent across APIs.

LeaVerou commented 1 week ago

Thank you for being responsive to our feedback.

Indeed, consistency is a good point, though depending on the use cases, it could end up being a good choice to change both of these methods. Therefore, it would still be good to list use cases (starting with user needs).

Nevertheless, we see a shadowRoots argument as a low-level primitive that could later be expanded so it's ok to start from it, especially if it has already shipped in other methods. I would reiterate that elementFromPoint() could also be expanded in the same way for consistency (and I suspect there are plenty of use cases for that too).

It's great to see support from additional implementers.

We’re going to go ahead and close this. Thank you for flying TAG!