@siliu1 have you reviewed the design principles?

* 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.

Updated description based on above feedbacks.

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.

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.

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!