[cssom-view] add shadowRoots parameter to caretPositionFromPoint …

…API. (#10200)

* Update Overview.bs

Per #9932, add `shadowRoots` parameter to `caretPositionFromPoint` API.

* Update Overview.bs

Bubble `caret range` out of the shadow roots.

* Update Overview.bs

Address PR comments.

* Update Overview.bs

Address PR comment.

* Update Overview.bs

Address PR comment.

* Update Overview.bs

linked created issue(10230) to the spec.

cssom-view-1/Overview.bs

@@ -1011,7 +1011,7 @@ Note: Some non-conforming implementations are known to return 32 instead of 24.
 partial interface Document {
  Element? elementFromPoint(double x, double y);
  sequence<Element> elementsFromPoint(double x, double y);
- CaretPosition? caretPositionFromPoint(double x, double y);
+ CaretPosition? caretPositionFromPoint(double x, double y, ShadowRoot... shadowRoots);
  readonly attribute Element? scrollingElement;
 };
 </pre>
@@ -1042,7 +1042,7 @@ instance, an element can be excluded from being a target for hit testing by usin
 1. If the document has a [=root element=], and the last item in <var>sequence</var> is not the [=root element=], append the [=root element=] to <var>sequence</var>.
 1. Return <var>sequence</var>.
 
-The <dfn method for=Document>caretPositionFromPoint(<var>x</var>, <var>y</var>)</dfn> method must return the
+The <dfn method for=Document>caretPositionFromPoint(<var>x</var>, <var>y</var>, ...<var>shadowRoots</var>)</dfn> method must return the
 result of running these steps:
 
 1. If there is no <a>viewport</a> associated with the document, return null.
@@ -1070,21 +1070,18 @@ result of running these steps:
  <dt><a>caret range</a>
  <dd>null
  </dl>
-1. Otherwise, return a <a>caret position</a> where the
- <a>caret range</a> is a collapsed
- {{Range}} object for the position
- where the text insertion point indicator would have been inserted when applying the <a>transforms</a> that apply to the descendants of the
- <a>viewport</a>, and the other properties are set as follows:
-
- <dl>
- <dt><a>caret node</a>
- <dd>The [=range/start node=]
- of the <a>caret range</a>.
-
- <dt><a>caret offset</a>
- <dd>The [=range/start offset=] of
- the <a>caret range</a>.
- </dl>
+1. Otherwise:
+
+ 1. Let <var>caretPosition</var> be a <a for=/>tuple</a> consisting of a <var>caretPositionNode</var> (a <a for=/>node</a>) and a <var>caretPositionOffset</var> (a non-negative integer) for the position where the text insertion point indicator would have been inserted when applying
+ the <a>transforms</a> that apply to the descendants of the <a>viewport</a>.
+ 1. Let <var>startNode</var> be the <var>caretPositionNode</var> of the <var>caretPosition</var>, and let <var>startOffset</var> be the <var>caretPositionOffset</var> of the <var>caretPosition</var>.
+ 1. While <var>startNode</var> is a [=node=], <var>startNode</var>'s [=tree/root=] is a [=shadow root=], and <var>startNode</var>'s [=tree/root=] is not a [=shadow-including inclusive ancestor=] of any of <var>shadowRoots</var>, repeat these steps:
+ 1. Set <var>startOffset</var> to [=tree/index=] of <var>startNode</var>'s [=tree/root=]'s [=host=].
+ 1. Set <var>startNode</var> to <var>startNode</var>'s [=tree/root=]'s [=host=]'s [=tree/parent=].</li>
+ 1. Return a <a>caret position</a> with its properties set as follows:
+ 1. <a>caret node</a> is set to <var>startNode</var>.
+ 1. <a>caret offset</a> is set to <var>startOffset</var>.
+ 1. <a>caret range</a> is set to a collapsed {{Range}} object which [=range/start node=] and [=range/end node=] are <var>startNode</var>, and which [=range/start offset=] and [=range/end offset=] are <var>startOffset</var>.
 
 Note: The specifics of hit testing are out of scope of this
 specification and therefore the exact details of
@@ -1148,6 +1145,8 @@ aborting on the first step that returns a value:
 
 Note: This {{DOMRect}} object is not <a spec=html>live</a>.
 
+Issue(10230): Consider removing <a>caret range</a> concept from <dfn>caret position</dfn> interface.
+
 <h2 id=extension-to-the-element-interface caniuse="element-scroll-methods">
 Extensions to the {{Element}} Interface</h2>