[cssom-view-1] Define caretRangeFromPoint()

cssom-view-1/Overview.bs

@@ -1024,6 +1024,7 @@ partial interface Document {
   Element? elementFromPoint(double x, double y);
   sequence<Element> elementsFromPoint(double x, double y);
   CaretPosition? caretPositionFromPoint(double x, double y, optional <span>CaretPositionFromPointOptions</span> options = {});
+  Range? caretRangeFromPoint(double x, double y);
   readonly attribute Element? scrollingElement;
 };
 
@@ -1097,6 +1098,52 @@ result of running these steps:
 
 Note: This <a>caret position</a> is not <a spec=html>live</a>.
 
+The <dfn method for=Document>caretRangeFromPoint(<var>x</var>, <var>y</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.
+1. If either argument is negative, <var>x</var> is greater
+    than the <a>viewport</a> width excluding the size of a rendered
+    scroll bar (if any), <var>y</var> is greater than the
+    <a>viewport</a> height excluding the size of a rendered scroll bar
+    (if any) return null.
+1. If at the coordinates <var>x</var>,<var>y</var>
+    in the <a>viewport</a> no text insertion point indicator would have
+    been inserted when applying the <a>transforms</a> that apply to the descendants of the <a>viewport</a>, return null.
+1. If at the coordinates <var>x</var>,<var>y</var>
+    in the <a>viewport</a> a text insertion point indicator would have
+    been inserted in a text entry widget which is also a replaced element, when applying the <a>transforms</a> that apply to the descendants of the
+    <a>viewport</a>, return a <a>range</a> with its properties set as follows:
+
+    <dl>
+        <dt><a>range start node</a>
+        <dd>The node corresponding to the text entry widget.
+
+        <dt><a>range end node</a>
+        <dd>The node corresponding to the text entry widget.
+
+        <dt><a>range start offset</a>
+        <dd>The amount of 16-bit units to the left of where the
+        text insertion point indicator would have inserted.
+
+        <dt><a>range end offset</a>
+        <dd>The amount of 16-bit units to the left of where the
+        text insertion point indicator would have inserted.
+    </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>options</var>["{{CaretPositionFromPointOptions/shadowRoots}}"], 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=].
+    1. Return a <a>range</a> with its properties set as follows:
+        1. <a>range start node</a> is set to <var>startNode</var>.
+        1. <a>range end node</a> is set to <var>startNode</var>.
+        1. <a>range start offset</a> is set to <var>startOffset</var>.
+        1. <a>range end offset</a> is set to <var>startOffset</var>.
+
 Note: The specifics of hit testing are out of scope of this
 specification and therefore the exact details of
 {{elementFromPoint()}} and {{caretPositionFromPoint()}}