feat: add experimental positioning for default EPUB decoration styles

this will position decorations between text and background, allowing for opaque highlight colors

Author: ddfreiling

readium/navigator/src/main/java/org/readium/r2/navigator/epub/EpubNavigatorFragment.kt

@@ -8,6 +8,7 @@
 
 package org.readium.r2.navigator.epub
 
+import android.graphics.Color
 import android.graphics.PointF
 import android.graphics.RectF
 import android.os.Bundle
@@ -20,6 +21,7 @@ import android.webkit.JavascriptInterface
 import android.webkit.WebResourceRequest
 import android.webkit.WebResourceResponse
 import android.webkit.WebView
+import androidx.annotation.ColorInt
 import androidx.collection.forEach
 import androidx.constraintlayout.widget.ConstraintLayout
 import androidx.core.os.BundleCompat
@@ -214,14 +216,17 @@ public class EpubNavigatorFragment internal constructor(
         public constructor(
             servedAssets: List<String> = emptyList(),
             readiumCssRsProperties: RsProperties = RsProperties(),
-            decorationTemplates: HtmlDecorationTemplates = HtmlDecorationTemplates.defaultTemplates(),
+            decorationTemplates: HtmlDecorationTemplates? = null,
             disablePageTurnsWhileScrolling: Boolean = false,
             selectionActionModeCallback: ActionMode.Callback? = null,
             shouldApplyInsetsPadding: Boolean? = true,
+            experimentalDecorationPositioning: Boolean? = false,
         ) : this(
             servedAssets = servedAssets,
             readiumCssRsProperties = readiumCssRsProperties,
-            decorationTemplates = decorationTemplates,
+            decorationTemplates = decorationTemplates ?: HtmlDecorationTemplates.defaultTemplates(
+                experimentalPositioning = experimentalDecorationPositioning == true
+            ),
             disablePageTurnsWhileScrolling = disablePageTurnsWhileScrolling,
             selectionActionModeCallback = selectionActionModeCallback,
             shouldApplyInsetsPadding = shouldApplyInsetsPadding,
@@ -259,6 +264,27 @@ public class EpubNavigatorFragment internal constructor(
             )
         }
 
+        /**
+         * Update default decorations, to change styling and positioning.
+         */
+        public fun updateDefaultDecorations(
+            @ColorInt defaultTint: Int = Color.YELLOW,
+            lineWeight: Int = 2,
+            cornerRadius: Int = 3,
+            alpha: Double = 0.3,
+            experimentalPositioning: Boolean = false,
+        ) {
+                val updatedDefaultTemplates =
+                    HtmlDecorationTemplates.defaultTemplates(
+                        defaultTint,
+                        lineWeight,
+                        cornerRadius,
+                        alpha,
+                        experimentalPositioning,
+                    )
+                decorationTemplates = decorationTemplates.copyWith(updatedDefaultTemplates)
+            }
+
         public companion object {
             public operator fun invoke(builder: Configuration.() -> Unit): Configuration =
                 Configuration().apply(builder)

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) */
@@ -201,6 +210,13 @@ public class HtmlDecorationTemplates private constructor(
 
     public fun copy(): HtmlDecorationTemplates = HtmlDecorationTemplates(styles.toMutableMap())
 
+    public fun copyWith(other: HtmlDecorationTemplates): HtmlDecorationTemplates =
+        copy().apply {
+            other.styles.forEach { (key, value) ->
+                styles[key] = value
+            }
+        }
+
     public companion object {
         public operator fun invoke(build: HtmlDecorationTemplates.() -> Unit): HtmlDecorationTemplates =
             HtmlDecorationTemplates().apply(build)
@@ -213,14 +229,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 +247,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

@@ -87,6 +87,9 @@ class EpubReaderFragment : VisualReaderFragment() {
                     decorationTemplates[DecorationStyleAnnotationMark::class] = annotationMarkTemplate()
                     decorationTemplates[DecorationStylePageNumber::class] = pageNumberTemplate()
 
+                    // Update default decorations to be opaque and use experimental positioning.
+                    updateDefaultDecorations(experimentalPositioning = true, alpha = 1.0)
+
                     // Declare a custom font family for reflowable EPUBs.
                     addFontFamilyDeclaration(FontFamily.LITERATA) {
                         addFontFace {