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

[ffiori]

Add highlightsFromPoint() to CSS.highlights as discussed in #7513.

[siliu1]

would it be better to add another sentence to explain in further details what this API do?

[dandclark]

Maybe even a code sample showing its use in a click event handler or something like that.

[siliu1]

should we add link to the definition of range?

[siliu1]

maybe link to the definition of getClientRects()?

[dandclark]

Also instead of "calling getClientRects() on it" let's say "calling getClientRects() on <var>range</var>".

[dandclark]

And instead of "one of the rectangles" we can say "one of the {{DOMRects}}"

[dandclark]

Maybe even a code sample showing its use in a click event handler or something like that.

[dandclark]

Can we do this to link to the definition of sequence?

Suggested change

	1. If there is no <a>viewport</a> associated with the document, return the empty sequence.
	1. If there is no <a>viewport</a> associated with the document, return the empty [=sequence=].

[dandclark]

I would suggest this change to make this step a bit more precise and easy to read:

1. If any of the following are true, return the empty sequence:
    * <var>x</var>is negative
    * <var>y</var>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)

[dandclark]

I recommend moving this Note to be adjacent to the step in the algorithm that hand-waves over the hit-testing details.

[dandclark]

Suggested change

	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
	1. The range's {{commonAncestorContainer}} is not in a [=shadow tree=] or is in a [=shadow tree=]s whose [=shadow root=] is [=contains|contained by=] by <var>options.shadowRoots</var>.

(Please confirm that the definition references here resolve properly. I'm trying to reference the shadow tree definition https://dom.spec.whatwg.org/#concept-shadow-tree, shadow root at https://dom.spec.whatwg.org/#concept-shadow-root, and contains at https://infra.spec.whatwg.org/#list-contain).

[dandclark]

The step should say something about where we're getting these highlights, e.g. "Return a sequence of [=custom highlights=] given by ordering the highlights contained in this {{HighlightRegistry}} by [=priority=], excluding the highlights without at least one range that satisfies the following constraints..."

[dandclark]

Suggested change

	where each highlight contains at least one range that satisfies the following constraints:
	where each highlight contains at least one {{Range}} <var>range</var> that satisfies the following constraints:

Making this a variable so we can reference it below in the getClientRects() call.

[dandclark]

Also instead of "calling getClientRects() on it" let's say "calling getClientRects() on <var>range</var>".

[dandclark]

And instead of "one of the rectangles" we can say "one of the {{DOMRects}}"