Skip to content

Add experimental EPUB decoration positioning #721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Nov 6, 2025
Merged

Add experimental EPUB decoration positioning #721

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bab2b19
feat: add experimental positioning for default EPUB decoration styles
ddfreiling Oct 31, 2025
affc4d0
chore: fix lint
ddfreiling Oct 31, 2025
ee4d8b7
Merge branch 'develop' into feat/highlight-z-index
mickael-menu Nov 6, 2025
532d167
refactor: simplify implementation
ddfreiling Nov 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]

Expand Down
20 changes: 16 additions & 4 deletions readium/navigator/src/main/java/org/readium/r2/navigator/html/HtmlDecorationTemplate.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. */
Expand All @@ -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,
)

/**
Expand All @@ -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)
Expand All @@ -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()};")
}
Expand All @@ -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) */
Expand Down Expand Up @@ -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(
Expand All @@ -229,7 +240,8 @@ public class HtmlDecorationTemplates private constructor(
defaultTint = defaultTint,
lineWeight = lineWeight,
cornerRadius = cornerRadius,
alpha = alpha
alpha = alpha,
experimentalPositioning = experimentalPositioning,
)
)
}
Expand Down
8 changes: 8 additions & 0 deletions test-app/src/main/java/org/readium/r2/testapp/reader/EpubReaderFragment.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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()
Expand Down