[css-highlight-api-1] Add highlightsFromPoint() to CSS.highlights #7513

css-highlight-api-1/Overview.bs

@@ -233,7 +233,7 @@ Registering Custom Highlights</h3>
 	};
 
 	[Exposed=Window]
-	interface HighlightRegistry {
+	partial interface HighlightRegistry {
 		maplike<DOMString, Highlight>;
 	};
 	</xmp>
@@ -579,6 +579,42 @@ Range Updating and Invalidation</h3>
 	is not <a spec=dom for="StaticRange">valid</a>,
 	the user agent must ignore that [=range=].
 
+<h2 id="interactions">
+Interacting with Custom Highlights</h2>
+
+User interaction with [=custom highlights=] can be done via the
+ {{highlightsFromPoint}}(<var>x</var>, <var>y</var>, <var>options</var>) method.
+
+<pre class=idl>
+partial interface HighlightRegistry {
+  sequence&lt;Highlight> highlightsFromPoint(float x, float y, optional <span>HighlightsFromPointOptions</span> options = {});
+};
+
+dictionary <dfn dictionary>HighlightsFromPointOptions</dfn> {
+  sequence&lt;ShadowRoot> <dfn dict-member for="HighlightsFromPointOptions">shadowRoots</dfn> = [];
+};
+</pre>
+
+	The <dfn method for="HighlightRegistry">highlightsFromPoint(<var>x</var>, <var>y</var>, <var>options</var>)</dfn>
+	 method must return the result of running these steps:
+
+1. If there is no <a>viewport</a> associated with the document, return the empty sequence.
+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), or <var>y</var> is greater than the
+    <a>viewport</a> height excluding the size of a rendered scroll bar
+    (if any), return the empty sequence.
+1. Otherwise, return a sequence of custom higlights ordered by [=priority=],
+    where each highlight contains at least one range that satisfies the following constraints:
+	1. The coordinates <var>x</var>,<var>y</var> fall inside at least one of the rectangles returned by calling getClientRects() on it.
+	1. The range's {{commonAncestorContainer}} is not in a shadow DOM, or is one of the shadow roots passed in <var>options</var> or a
+	    descendant of one of them.
+
+Note: The specifics of hit testing are out of scope of this
+specification and therefore the exact details of
+{{highlightsFromPoint()}} are therefore too. Hit testing
+will hopefully be defined in a future revision of CSS or HTML.
+
 <h2 id=events>
 Event Handling</h2>
 
@@ -629,6 +665,9 @@ Changes since the <a href="https://www.w3.org/TR/2020/WD-css-highlight-api-1-202
 	In addition to various editorial improvements and minor tweaks,
 	the main changes are:
 
+	* Added a {{HighlightRegistry/highlightsFromPoint}} method to
+	    {{HighlightRegistry}}.
+		(See <a href="https://github.com/w3c/csswg-drafts/pull/7513">Issue 7513</a>)
 	* Specified that highlight repainting has to be done asynchronously.
 		(See <a href="https://github.com/w3c/csswg-drafts/pull/6987">Issue 6987</a>)
 	* Clarify that UAs cannot specify paired default highlight colors for custom highlights.