Skip to content

Commit b394536

Browse files
ffioriffiori
authored
[css-highlight-api-1] Add highlightsFromPoint() to CSS.highlights w3c#7513 (w3c#11507)
* add spec for highlightsFromPoint
1 parent ef8d1f6 commit b394536

File tree

1 file changed

+105
-2
lines changed

1 file changed

+105
-2
lines changed

‎css-highlight-api-1/Overview.bs

+105-2
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,9 @@ spec:css-color-4; type:property; text:color
4949
spec:css-pseudo-4; type:dfn; text:highlight overlay
5050
spec:dom; type:dfn; text:range
5151
spec:css-values-4; type:dfn; text:identifier
52+
spec:dom; type:dfn; for:Element; text:shadow root
53+
spec:dom; type:dfn; text:event
54+
spec:css21; type:dfn; text:viewport
5255
</pre>
5356

5457
<style>
@@ -73,7 +76,7 @@ Introduction</h2>
7376
''::selection'',
7477
''::inactive-selection'',
7578
''::spelling-error'',
76-
and '''::grammar-error'''.
79+
and ''::grammar-error''.
7780
This is useful in a variety of scenarios,
7881
including editing frameworks that wish to implement their own selection,
7982
find-on-page over virtualized documents,
@@ -233,7 +236,7 @@ Registering Custom Highlights</h3>
233236
};
234237

235238
[Exposed=Window]
236-
interface HighlightRegistry {
239+
partial interface HighlightRegistry {
237240
maplike<DOMString, Highlight>;
238241
};
239242
</xmp>
@@ -579,6 +582,103 @@ Range Updating and Invalidation</h3>
579582
is not <a spec=dom for="StaticRange">valid</a>,
580583
the user agent must ignore that [=range=].
581584

585+
<h2 id="interactions">
586+
Interacting with Custom Highlights</h2>
587+
588+
The {{highlightsFromPoint}}(<var>x</var>, <var>y</var>, <var>options</var>) method allows developers to build scenarios
589+
involving user interaction with [=custom highlights=]. The method returns a [=sequence=] containing the [=custom highlights=]
590+
at a given <var>x</var>, <var>y</var> coordinate. The [=custom highlights=] are listed in this [=sequence=] in
591+
descending [=priority=] order.
592+
By default, [=custom highlights=] in a [=shadow tree=] are not returned, but the developer has the possibility to pass in
593+
an optional <var>options</var> [=dictionary=] with a <var>shadowRoots</var> property containing a [=sequence=] of {{ShadowRoot}}
594+
objects. [=custom highlights|Highlights=] contained within a [=shadow tree=] provided in this way will be returned.
595+
596+
<div class=example id=highlights-from-point-ex>
597+
The following example shows a way to use {{highlightsFromPoint}} to interact with mouse click [=event|events=].
598+
599+
<xmp highlight=html>
600+
<style>
601+
:root::highlight(foo) {
602+
background-color:yellow;
603+
}
604+
:root::highlight(bar) {
605+
color:red;
606+
}
607+
</style>
608+
<body>abc
609+
<script>
610+
document.addEventListener('click', (event) => {
611+
const mouseX = event.clientX;
612+
const mouseY = event.clientY;
613+
console.log(CSS.highlights.highlightsFromPoint(mouseX, mouseY));
614+
});
615+
616+
let textNode = document.body.firstChild;
617+
let r1 = new Range();
618+
r1.setStart(textNode, 0);
619+
r1.setEnd(textNode, 2);
620+
let r2 = new Range();
621+
r2.setStart(textNode, 1);
622+
r2.setEnd(textNode, 2);
623+
624+
let h1 = new Highlight(r1);
625+
let h2 = new Highlight(r2);
626+
h1.priority = 1;
627+
h2.priority = 2;
628+
629+
CSS.highlights.set("foo", h1);
630+
CSS.highlights.set("bar", h2);
631+
</script>
632+
</xmp>
633+
634+
The code above will display the following styled text, note that "b" is affected by both [=custom highlight|highlights=]
635+
<var>h1</var> and <var>h2</var>, whereas "a" is only affected by <var>h1</var>:
636+
637+
<div class=sample-out style="color:black">
638+
<span style="background:yellow;">a</span><span style="background:yellow;color:red;">b</span><span>c</span>
639+
</div>
640+
641+
In this example there's an [=event listener=] set on click [=event|events=] that logs the [=custom highlights=]
642+
present at the point where the click was made.
643+
The following [=sequence|sequences=] are some examples of what will be printed to console after a click:
644+
* <code>[ <var>h1</var> ]</code>, if the user clicks on character "a".
645+
* <code>[ <var>h2</var>, <var>h1</var> ]</code>, if the user clicks on character "b",
646+
as <var>h2</var> has higher priority than <var>h1</var>.
647+
* <code>[]</code>, if the user clicks on character "c".
648+
</div>
649+
650+
The method {{highlightsFromPoint}} is defined as part of the {{HighlightRegistry}} interface as follows:
651+
652+
<pre class=idl>
653+
partial interface HighlightRegistry {
654+
sequence&lt;Highlight> highlightsFromPoint(float x, float y, optional <span>HighlightsFromPointOptions</span> options = {});
655+
};
656+
657+
dictionary <dfn dictionary>HighlightsFromPointOptions</dfn> {
658+
sequence&lt;ShadowRoot> <dfn dict-member for="HighlightsFromPointOptions">shadowRoots</dfn> = [];
659+
};
660+
</pre>
661+
662+
The <dfn method for="HighlightRegistry">highlightsFromPoint(<var>x</var>, <var>y</var>, <var>options</var>)</dfn>
663+
method must return the result of running these steps:
664+
665+
1. If any of the following are true, return the empty [=sequence=]:
666+
* <var>x</var> is negative
667+
* <var>y</var> is negative
668+
* <var>x</var> is greater than the <a>viewport</a> width excluding the size of a rendered scroll bar (if any)
669+
* <var>y</var> is greater than the <a>viewport</a> height excluding the size of a rendered scroll bar (if any)
670+
1. Otherwise, return a [=sequence=] of [=custom highlights=] given by ordering the highlights contained in this {{HighlightRegistry}} in descending order of [=priority=],
671+
excluding the highlights without at least one [=range=] <var>range</var> that satisfies the following constraints:
672+
1. The coordinates <var>x</var>,<var>y</var> fall inside at least one of the {{DOMRect}}s returned by calling {{Range/getClientRects()}} on <var>range</var>.
673+
674+
Note: The specifics of hit testing are out of scope of this
675+
specification and therefore the exact details of
676+
{{highlightsFromPoint()}} are therefore too. Hit testing
677+
will hopefully be defined in a future revision of CSS or HTML.
678+
679+
1. The <var>range</var>'s {{commonAncestorContainer}} is not in a [=shadow tree=] or is in a [=shadow tree=] whose
680+
[=shadow root=] is [=list/contains|contained by=] by <var>options</var>.<var>shadowRoots</var>.
681+
582682
<h2 id=events>
583683
Event Handling</h2>
584684

@@ -629,6 +729,9 @@ Changes since the <a href="https://www.w3.org/TR/2020/WD-css-highlight-api-1-202
629729
In addition to various editorial improvements and minor tweaks,
630730
the main changes are:
631731

732+
* Added a {{HighlightRegistry/highlightsFromPoint}} method to
733+
{{HighlightRegistry}}.
734+
(See <a href="https://github.com/w3c/csswg-drafts/pull/7513">Issue 7513</a>)
632735
* Specified that highlight repainting has to be done asynchronously.
633736
(See <a href="https://github.com/w3c/csswg-drafts/pull/6987">Issue 6987</a>)
634737
* Clarify that UAs cannot specify paired default highlight colors for custom highlights.

0 commit comments

Comments
 (0)