From b3945367e01dad701f610d54cdc1685e3e05b4ce Mon Sep 17 00:00:00 2001 From: Fernando Fiori Date: Sat, 25 Jan 2025 02:38:49 -0300 Subject: [PATCH] [css-highlight-api-1] Add highlightsFromPoint() to CSS.highlights #7513 (#11507) * add spec for highlightsFromPoint --- css-highlight-api-1/Overview.bs | 107 +++++++++++++++++++++++++++++++- 1 file changed, 105 insertions(+), 2 deletions(-) diff --git a/css-highlight-api-1/Overview.bs b/css-highlight-api-1/Overview.bs index d7f44c4c4df4..aa09f5f5c536 100644 --- a/css-highlight-api-1/Overview.bs +++ b/css-highlight-api-1/Overview.bs @@ -49,6 +49,9 @@ spec:css-color-4; type:property; text:color spec:css-pseudo-4; type:dfn; text:highlight overlay spec:dom; type:dfn; text:range spec:css-values-4; type:dfn; text:identifier +spec:dom; type:dfn; for:Element; text:shadow root +spec:dom; type:dfn; text:event +spec:css21; type:dfn; text:viewport + abc + + + + The code above will display the following styled text, note that "b" is affected by both [=custom highlight|highlights=] + h1 and h2, whereas "a" is only affected by h1: + +
+ abc +
+ + In this example there's an [=event listener=] set on click [=event|events=] that logs the [=custom highlights=] + present at the point where the click was made. + The following [=sequence|sequences=] are some examples of what will be printed to console after a click: + * [ h1 ], if the user clicks on character "a". + * [ h2, h1 ], if the user clicks on character "b", + as h2 has higher priority than h1. + * [], if the user clicks on character "c". + + +The method {{highlightsFromPoint}} is defined as part of the {{HighlightRegistry}} interface as follows: + +
+partial interface HighlightRegistry {
+	sequence<Highlight> highlightsFromPoint(float x, float y, optional HighlightsFromPointOptions options = {});
+};
+
+dictionary HighlightsFromPointOptions {
+	sequence<ShadowRoot> shadowRoots = [];
+};
+
+ +The highlightsFromPoint(x, y, options) +method must return the result of running these steps: + +1. If any of the following are true, return the empty [=sequence=]: + * x is negative + * y is negative + * x is greater than the viewport width excluding the size of a rendered scroll bar (if any) + * y is greater than the viewport height excluding the size of a rendered scroll bar (if any) +1. Otherwise, return a [=sequence=] of [=custom highlights=] given by ordering the highlights contained in this {{HighlightRegistry}} in descending order of [=priority=], + excluding the highlights without at least one [=range=] range that satisfies the following constraints: + 1. The coordinates x,y fall inside at least one of the {{DOMRect}}s returned by calling {{Range/getClientRects()}} on range. + + 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. + + 1. The range's {{commonAncestorContainer}} is not in a [=shadow tree=] or is in a [=shadow tree=] whose + [=shadow root=] is [=list/contains|contained by=] by options.shadowRoots. +

Event Handling

@@ -629,6 +729,9 @@ Changes since the Issue 7513) * Specified that highlight repainting has to be done asynchronously. (See Issue 6987) * Clarify that UAs cannot specify paired default highlight colors for custom highlights.