Relation between HighlightRange#priority and other highlight pseudo elements

[gked]

moving from https://github.com/dlibby-/highlight/issues/13
@Reinmar as FYI

As I understand, HighlightRange#priority is needed to control which highlight is rendered above which. Since we have other highlight pseudo-elements like ::selection or :spelling-error, could we prioritize our highlight range above those?

In other words – do the UA's highlight pseud-elements have defined priorities?

Crazy idea – couldn't z-index be used for that instead of priorities?

[sanketj]

Thanks for this feedback @Reinmar. I think there are two pieces to this: (1) defining a default priority for all highlight pseudo elements, and (2) providing authors with a way to change how the ::highlight pseudo is prioritized relative to other pseudos. Please see my thoughts about each of these below.

(1)
The scenarios in which authors would be using the ::highlight pseudo together with one of the other pseudos would be when the author is using the highlight API to build some custom editing capability, while also using browser native behavior for some other editing capability. For example, if an author is using the highlight API to create a custom find-on-page and continues to use the browser's native selection, they may use a ::highlight pseudo to style find results and a ::selection pseudo to style the selected content. An author is unlikely to use the ::selection pseudo if they are creating a custom selection (same goes for spellchecking and grammar checking).

Since the author cares about native highlights in such cases, we need to make sure that the rendering of the native selection, spellchecking or grammar checking isn't inadvertently suppressed by author-defined highlights. (In the example above, we wouldn't want the user's find-on-page highlights to be rendered on top of the selection.) Therefore, I propose that we define the default priority of ::highlight to be lower than all other highlight pseudo elements. For existing pseudos, the spec (https://drafts.csswg.org/css-pseudo-4/#highlight-painting) states that the "::selection overlay is drawn over the ::spelling-error overlay which is drawn over the ::grammar-error overlay", which means that the priority order is selection > spelling-error > grammar-error. With ::highlight in the picture, the new order would be: selection > spelling-error > grammar-error > highlight.

(2)
The priority property on HighlightRangeGroup can be used to prioritize one ::highlight pseudo over another - we can extend this mechanism to provide a way to also prioritize ::highlight pseudos relative to other pseudos. Below are two possible solutions.

(a)
Define the default priority of the ::highlight pseudo to be 0, and the priorities of other pseudos to be between 0 and 1 (ex. grammar-error: 0.25, spelling-error: 0.5, selection: 0.75). Also define that the HighlightRangeGroup's priority property can only be set to integer values. The author can then use positive priority values to stack their highlights above native highlights, and use 0 or negative values to keep them below. The benefit of this approach is that the author doesn't need to know about the exact priority values of native highlights (those remain an implementation detail). It also leaves enough room to properly prioritize any new native highlights that are added in the future, like w3c/csswg-drafts#3812. The limitation of this approach is that users cannot stack their highlights in between native highlights. For example, if the author is building a spellchecker, they cannot create a custom spellcheck highlight and prioritize it between native grammar checking and native selection.

(b)
Define the default priority of the ::highlight pseudo to be 0, and the priorities of other pseudos to be integer values higher than that, while leaving some room in between (ex. grammar-error: 10, spelling-error: 20, selection: 30). This not only leaves space for future native highlights, but also allows authors to place their custom highlights in between native highlights. So in the example from (a), the author could give their custom spellcheck highlight a priority between 10 and 30 to stack it between native grammar checking and native selection. The downside with this approach is that the priorities of native highlights need to be exposed.

My preference would be option (a) because there is no known scenario that absolutely requires a user highlight to be stacked in between two native highlights. To reason about this better, let's include the native highlight for find-on-page in our stacking order (this exists in the browser today, but isn't exposed via CSS - see w3c/csswg-drafts#3812), and let's assume the order to be: selection > spelling-error > grammar-error > find-on-page. The interesting scenarios would be if the author wanted to replace spelling-error or grammar-error, or both.

If the author wanted to replace grammar-error but keep it behind the native spelling-error, they could prioritize their custom grammar check highlight lower than all the native highlights (behind find-on-page). This would work assuming the author doesn't use the same styles as find-on-page for their custom grammar checking, which seems highly likely. Find-on-page would apply background-color, and maybe color, while the grammar checking may apply text-decoration to show green squiggles. Since the properties don't conflict, the author's grammar highlight would still be visible.

Similarly, if the author instead wanted to replace spelling-error and keep it in front of native grammar-error, they could prioritize their custom spellcheck highlight above all native highlights. Since selection should apply different properties (background color, color) to the author's custom spelling error (ex. text decoration), the selection will still be visible.

If the author wants to replace both spellchecking and grammar checking - this is the case for extensions like Grammarly - then they have the choice to place them above or below the native highlights, either would work. To keep spellchecking above grammar checking, they could assign their custom spellcheck highlights a higher priority than the custom grammar highlights.

This model will also hold for any new native highlights that are introduced in the future. Authors can replace any native highlight from the middle of the stack and still achieve "native-esque" ordering, as long as the pieces that changed order do not have conflicting styles.

[frivoal]

Since the spec is now in the css-wg, I suggest moving the discussion there and closing this issue. w3c/csswg-drafts#4594 is largely the same topic. You may want to repeat your comments there.

[sanketj]

Closing this issue. This has now been moved to the CSS WG drafts repo (see link above).