Add experimental EPUB decoration positioning (#721)

Author: ddfreiling

CHANGELOG.md

@@ -4,7 +4,15 @@ All notable changes to this project will be documented in this file. Take a look
 
 **Warning:** Features marked as *experimental* may change or be removed in a future release without notice. Use with caution.
 
-<!-- ## [Unreleased] -->
+## [Unreleased]
+
+### Added
+
+#### Navigator
+
+* New experimental positioning of EPUB decorations that places highlights behind text to improve legibility with opaque decorations (contributed by [@ddfreiling](https://github.com/readium/kotlin-toolkit/pull/721)).
+    * To opt-in, initialize the `EpubNavigatorFragment.Configuration` object with `decorationTemplates = HtmlDecorationTemplates.defaultTemplates(alpha = 1.0, experimentalPositioning = true)`.
+
 
 ## [3.1.2]
 

readium/navigator/src/main/java/org/readium/r2/navigator/html/HtmlDecorationTemplate.kt

@@ -94,13 +94,15 @@ public data class HtmlDecorationTemplate(
             lineWeight: Int,
             cornerRadius: Int,
             alpha: Double,
+            experimentalPositioning: Boolean = false,
         ): HtmlDecorationTemplate =
             createTemplate(
                 asHighlight = true,
                 defaultTint = defaultTint,
                 lineWeight = lineWeight,
                 cornerRadius = cornerRadius,
-                alpha = alpha
+                alpha = alpha,
+                experimentalPositioning = experimentalPositioning,
             )
 
         /** Creates a new decoration template for the underline style. */
@@ -109,13 +111,15 @@ public data class HtmlDecorationTemplate(
             lineWeight: Int,
             cornerRadius: Int,
             alpha: Double,
+            experimentalPositioning: Boolean = false,
         ): HtmlDecorationTemplate =
             createTemplate(
                 asHighlight = false,
                 defaultTint = defaultTint,
                 lineWeight = lineWeight,
                 cornerRadius = cornerRadius,
-                alpha = alpha
+                alpha = alpha,
+                experimentalPositioning = experimentalPositioning,
             )
 
         /**
@@ -128,6 +132,7 @@ public data class HtmlDecorationTemplate(
             lineWeight: Int,
             cornerRadius: Int,
             alpha: Double,
+            experimentalPositioning: Boolean = false,
         ): HtmlDecorationTemplate {
             val className = createUniqueClassName(if (asHighlight) "highlight" else "underline")
             val padding = Padding(left = 1, right = 1)
@@ -141,6 +146,9 @@ public data class HtmlDecorationTemplate(
                         if (asHighlight || isActive) {
                             append("background-color: ${tint.toCss(alpha = alpha)} !important;")
                         }
+                        if (experimentalPositioning) {
+                            append("--decoration-z-index: -1;")
+                        }
                         if (!asHighlight || isActive) {
                             append("--underline-color: ${tint.toCss()};")
                         }
@@ -154,6 +162,7 @@ public data class HtmlDecorationTemplate(
                 border-radius: ${cornerRadius}px;
                 box-sizing: border-box;
                 border: 0 solid var(--underline-color);
+                z-index: var(--decoration-z-index);
             }
             
             /* Horizontal (default) */
@@ -213,14 +222,16 @@ public class HtmlDecorationTemplates private constructor(
             lineWeight: Int = 2,
             cornerRadius: Int = 3,
             alpha: Double = 0.3,
+            experimentalPositioning: Boolean = false,
         ): HtmlDecorationTemplates = HtmlDecorationTemplates {
             set(
                 Style.Highlight::class,
                 HtmlDecorationTemplate.highlight(
                     defaultTint = defaultTint,
                     lineWeight = lineWeight,
                     cornerRadius = cornerRadius,
-                    alpha = alpha
+                    alpha = alpha,
+                    experimentalPositioning = experimentalPositioning,
                 )
             )
             set(
@@ -229,7 +240,8 @@ public class HtmlDecorationTemplates private constructor(
                     defaultTint = defaultTint,
                     lineWeight = lineWeight,
                     cornerRadius = cornerRadius,
-                    alpha = alpha
+                    alpha = alpha,
+                    experimentalPositioning = experimentalPositioning,
                 )
             )
         }

test-app/src/main/java/org/readium/r2/testapp/reader/EpubReaderFragment.kt

@@ -29,6 +29,7 @@ import org.readium.r2.navigator.Decoration
 import org.readium.r2.navigator.epub.*
 import org.readium.r2.navigator.epub.css.FontStyle
 import org.readium.r2.navigator.html.HtmlDecorationTemplate
+import org.readium.r2.navigator.html.HtmlDecorationTemplates
 import org.readium.r2.navigator.html.toCss
 import org.readium.r2.navigator.preferences.FontFamily
 import org.readium.r2.shared.ExperimentalReadiumApi
@@ -83,6 +84,13 @@ class EpubReaderFragment : VisualReaderFragment() {
                         "annotation-icon.svg"
                     )
 
+                    // Enable experimental decorations positioning that places highlights behind
+                    // text to improve legibility with opaque decorations.
+                    decorationTemplates = HtmlDecorationTemplates.defaultTemplates(
+                        alpha = 1.0,
+                        experimentalPositioning = true
+                    )
+
                     // Register the HTML templates for our custom decoration styles.
                     decorationTemplates[DecorationStyleAnnotationMark::class] = annotationMarkTemplate()
                     decorationTemplates[DecorationStylePageNumber::class] = pageNumberTemplate()