From 75cfe17e2a85d2efefeeca04a576971b2a748059 Mon Sep 17 00:00:00 2001 From: Fernando Fiori Date: Wed, 15 Jan 2025 18:27:09 -0300 Subject: [PATCH 1/3] add spec for highlightsFromPoint --- css-highlight-api-1/Overview.bs | 41 ++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/css-highlight-api-1/Overview.bs b/css-highlight-api-1/Overview.bs index d7f44c4c4df4..bbcc7db3a40c 100644 --- a/css-highlight-api-1/Overview.bs +++ b/css-highlight-api-1/Overview.bs @@ -233,7 +233,7 @@ Registering Custom Highlights }; [Exposed=Window] - interface HighlightRegistry { + partial interface HighlightRegistry { maplike; }; @@ -579,6 +579,42 @@ Range Updating and Invalidation is not valid, the user agent must ignore that [=range=]. +

+Interacting with Custom Highlights

+ +User interaction with [=custom highlights=] can be done via the + {{highlightsFromPoint}}(x, y, options) method. + +
+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 there is no viewport associated with the document, return the empty sequence. +1. If either argument is negative, x is greater + than the viewport width excluding the size of a rendered + scroll bar (if any), or y is greater than the + viewport 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 x,y 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 options 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. +

Event Handling

@@ -629,6 +665,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. From 0ab05c60271934d83abea0e8758a69f0cb840243 Mon Sep 17 00:00:00 2001 From: Fernando Fiori Date: Tue, 21 Jan 2025 16:07:18 -0800 Subject: [PATCH 2/3] add example and address feedback --- css-highlight-api-1/Overview.bs | 108 +++++++++++++++++++++++++------- 1 file changed, 85 insertions(+), 23 deletions(-) diff --git a/css-highlight-api-1/Overview.bs b/css-highlight-api-1/Overview.bs index bbcc7db3a40c..6c0c270985e5 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 [=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 = {});
+	sequence<Highlight> highlightsFromPoint(float x, float y, optional HighlightsFromPointOptions options = {});
 };
 
 dictionary HighlightsFromPointOptions {
-  sequence<ShadowRoot> shadowRoots = [];
+	sequence<ShadowRoot> shadowRoots = [];
 };
- The highlightsFromPoint(x, y, options) - method must return the result of running these steps: - -1. If there is no viewport associated with the document, return the empty sequence. -1. If either argument is negative, x is greater - than the viewport width excluding the size of a rendered - scroll bar (if any), or y is greater than the - viewport 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 x,y 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 options 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. +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}} by [=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. + 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. + + 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.

Event Handling

From 2a78a392ae1a08b4c22e7c296867c96f2f62453e Mon Sep 17 00:00:00 2001 From: Fernando Fiori Date: Fri, 24 Jan 2025 13:53:21 -0800 Subject: [PATCH 3/3] nits, address feedback --- css-highlight-api-1/Overview.bs | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/css-highlight-api-1/Overview.bs b/css-highlight-api-1/Overview.bs index 6c0c270985e5..aa09f5f5c536 100644 --- a/css-highlight-api-1/Overview.bs +++ b/css-highlight-api-1/Overview.bs @@ -585,12 +585,13 @@ Range Updating and Invalidation

Interacting with Custom Highlights

-User interaction with [=custom highlights=] can be done via the -{{highlightsFromPoint}}(x, y, options) method. -It returns a [=sequence=] of highlights at a given point, specified by coordinates x and y, -ordered by [=priority=]. The developer has the possibility to pass in options, which is an optional [=dictionary=] -where its [=keys|key=] maps to a [=sequence=] of {{ShadowRoot}} objects. -The API can search for and return highlights within the provided [=shadow tree=]. +The {{highlightsFromPoint}}(x, y, options) method allows developers to build scenarios +involving user interaction with [=custom highlights=]. The method returns a [=sequence=] containing the [=custom highlights=] +at a given x, y coordinate. The [=custom highlights=] are listed in this [=sequence=] in +descending [=priority=] order. +By default, [=custom highlights=] in a [=shadow tree=] are not returned, but the developer has the possibility to pass in +an optional options [=dictionary=] with a shadowRoots property containing a [=sequence=] of {{ShadowRoot}} +objects. [=custom highlights|Highlights=] contained within a [=shadow tree=] provided in this way will be returned.
The following example shows a way to use {{highlightsFromPoint}} to interact with mouse click [=event|events=]. @@ -630,7 +631,7 @@ The API can search for and return highlights within the provided [=shadow tree=] - The code above will display the following styled text, note that "b" is affected by both [=highlight|highlights=] + 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:
@@ -666,16 +667,17 @@ method must return the result of running these steps: * 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}} by [=priority=], +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. - 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. - 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. + 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