Skip to content

Commit b3a00e8

Browse files
authored
[css-highlight-api] Change highlightsFromPoint return type #12031 (#12215)
* change highlightsFromPoint return type * add case for shadow elements + fix typos/style * add exposed=Window to HighlightHitResult interface * make HighlightHitResult a dictionary * address feedback - change algorithm to more imperative, expand example * PR feedback - use 'let', catch exceptions * don't catch exceptions
1 parent 2587ef3 commit b3a00e8

File tree

1 file changed

+48
-30
lines changed

1 file changed

+48
-30
lines changed

css-highlight-api-1/Overview.bs

Lines changed: 48 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,8 @@ spec:dom; type:dfn; text:range
5151
spec:css-values-4; type:dfn; text:identifier
5252
spec:dom; type:dfn; for:Element; text:shadow root
5353
spec:dom; type:dfn; text:event
54-
spec:css21; type:dfn; text:viewport
54+
spec:css2; type:dfn; text:viewport
55+
spec:cssom-view; type:dfn; text:transforms
5556
</pre>
5657

5758
<style>
@@ -586,9 +587,9 @@ Range Updating and Invalidation</h3>
586587
Interacting with Custom Highlights</h2>
587588

588589
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.
590+
involving user interaction with [=custom highlights=]. The method returns a [=sequence=] containing {{HighlightHitResult}} objects
591+
which encapsulate the [=custom highlights=] and their [=ranges=] that are hit at a given <var>x</var>, <var>y</var> coordinate.
592+
This sequence is ordered by descending order of [=priority=] of its {{HighlightHitResult}}'s [=custom highlights|highlights=].
592593
By default, [=custom highlights=] in a [=shadow tree=] are not returned, but the developer has the possibility to pass in
593594
an optional <var>options</var> [=dictionary=] with a <var>shadowRoots</var> property containing a [=sequence=] of {{ShadowRoot}}
594595
objects. [=custom highlights|Highlights=] contained within a [=shadow tree=] provided in this way will be returned.
@@ -605,7 +606,7 @@ objects. [=custom highlights|Highlights=] contained within a [=shadow tree=] pro
605606
color:red;
606607
}
607608
</style>
608-
<body>abc
609+
<body>abcd
609610
<script>
610611
document.addEventListener('click', (event) => {
611612
const mouseX = event.clientX;
@@ -620,8 +621,11 @@ objects. [=custom highlights|Highlights=] contained within a [=shadow tree=] pro
620621
let r2 = new Range();
621622
r2.setStart(textNode, 1);
622623
r2.setEnd(textNode, 2);
624+
let r3 = new Range();
625+
r3.setStart(textNode, 3);
626+
r3.setEnd(textNode, 4);
623627

624-
let h1 = new Highlight(r1);
628+
let h1 = new Highlight(r1, r3);
625629
let h2 = new Highlight(r2);
626630
h1.priority = 1;
627631
h2.priority = 2;
@@ -632,26 +636,33 @@ objects. [=custom highlights|Highlights=] contained within a [=shadow tree=] pro
632636
</xmp>
633637

634638
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>:
639+
<var>h1</var> and <var>h2</var>, whereas "a" and "d" are only affected by <var>h1</var>:
636640

637641
<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>
642+
<span style="background:yellow;">a</span><span style="background:yellow;color:red;">b</span><span>c</span><span style="background:yellow;">d</span>
639643
</div>
640644

641645
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.
646+
and their ranges present at the point where the click was made.
643647
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>.
648+
* <code>[ HighlightHitResult {highlight: <var>h1</var>, ranges: [<var>r1</var>]} ]</code>, if the user clicks on character "a".
649+
Note that only <var>r1</var> is included in the {{HighlightHitResult}} returned since that's the only range in <var>h1</var> that was hit.
650+
* <code>[ HighlightHitResult {highlight: <var>h2</var>, ranges: [<var ignore=''>r2</var>]}, HighlightHitResult {highlight: <var>h1</var>, ranges: [<var>r1</var>]} ]</code>,
651+
if the user clicks on character "b", as <var>h2</var> has higher priority than <var>h1</var>.
647652
* <code>[]</code>, if the user clicks on character "c".
653+
* <code>[ HighlightHitResult {highlight: <var>h1</var>, ranges: [<var ignore=''>r3</var>]} ]</code>, if the user clicks on character "d".
648654
</div>
649655

650656
The method {{highlightsFromPoint}} is defined as part of the {{HighlightRegistry}} interface as follows:
651657

652658
<pre class=idl>
653659
partial interface HighlightRegistry {
654-
sequence&lt;Highlight> highlightsFromPoint(float x, float y, optional <span>HighlightsFromPointOptions</span> options = {});
660+
sequence&lt;HighlightHitResult> highlightsFromPoint(float x, float y, optional <span>HighlightsFromPointOptions</span> options = {});
661+
};
662+
663+
dictionary <dfn dictionary>HighlightHitResult</dfn> {
664+
Highlight <dfn dict-member>highlight</dfn>;
665+
sequence&lt;AbstractRange> <dfn dict-member>ranges</dfn>;
655666
};
656667

657668
dictionary <dfn dictionary>HighlightsFromPointOptions</dfn> {
@@ -665,23 +676,30 @@ method must return the result of running these steps:
665676
1. If any of the following are true, return the empty [=sequence=]:
666677
* <var>x</var> is negative
667678
* <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-
including only those highlights that contain at least one {{AbstractRange}} <var>abstractRange</var> that satisfies the following:
672-
673-
* Let <var>range</var> be a {{Range}} object whose [=start node=] and [=end node=] are set to <var>abstractRange</var>'s [=start node=] and [=end node=] respectively,
674-
and [=start offset=] and [=end offset=] are set to <var>abstractRange</var>'s [=start offset=] and [=end offset=] respectively.
675-
676-
* 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>.
677-
678-
Note: The specifics of hit testing are out of scope of this
679-
specification and therefore the exact details of
680-
{{highlightsFromPoint()}} are therefore too. Hit testing
681-
will hopefully be defined in a future revision of CSS or HTML.
682-
683-
* The <var>range</var>'s {{commonAncestorContainer}} is not in a [=shadow tree=] or is in a [=shadow tree=] whose
684-
[=shadow root=] is [=list/contains|contained by=] by <var>options</var>.<var>shadowRoots</var>.
679+
* <var>x</var> is greater than the [=viewport=] width excluding the size of a rendered scroll bar (if any)
680+
* <var>y</var> is greater than the [=viewport=] height excluding the size of a rendered scroll bar (if any)
681+
* The topmost [=box=] in the [=viewport=] in paint order that would be a target for hit testing at coordinates <var>x</var>,<var>y</var> when applying
682+
the [=transforms=] that apply to the descendants of the viewport, has an element associated to it that's in a [=shadow tree=] whose
683+
[=shadow root=] is not [=list/contains|contained by=] <var>options</var>.<var>shadowRoots</var>.
684+
1. Otherwise, let <var>results</var> be an empty [=sequence=].
685+
1. For each {{Highlight}} <var>highlight</var> in this {{HighlightRegistry}}:
686+
1. Let <var>result</var> be a new {{HighlightHitResult}} with {{HighlightHitResult/highlight}} set to <var>highlight</var>.
687+
1. For each {{AbstractRange}} <var>abstractRange</var> in <var>highlight</var>:
688+
1. If <var>abstractRange</var> is an [=StaticRange/valid|invalid=] {{StaticRange}}, then [=iteration/continue=].
689+
1. Let <var>range</var> be a new {{Range}} whose [=start node=] and [=end node=] are set to <var>abstractRange</var>'s
690+
[=start node=] and [=end node=] respectively, and [=start offset=] and [=end offset=] are set to <var>abstractRange</var>'s
691+
[=start offset=] and [=end offset=] respectively.
692+
1. If the coordinates <var>x</var>,<var>y</var> fall inside at least one of the {{DOMRect}}s returned by calling {{Range/getClientRects()}}
693+
on <var>range</var>, then append <var>abstractRange</var> to <var>result</var>.{{HighlightHitResult/ranges}}.
694+
695+
Note: The specifics of hit testing are out of scope of this
696+
specification and therefore the exact details of
697+
{{highlightsFromPoint()}} are too. Hit testing will
698+
hopefully be defined in a future revision of CSS or HTML.
699+
700+
1. If <var>result</var>.{{HighlightHitResult/ranges}} is not empty, append <var>result</var> to <var>results</var>.
701+
1. Sort <var>results</var> by descending order of [=priority=] of its {{HighlightHitResult}}s' {{HighlightHitResult/highlight}} attributes.
702+
1. Return <var>results</var>.
685703

686704
<h2 id=events>
687705
Event Handling</h2>

0 commit comments

Comments
 (0)