Various changes for v3 (#367)

CHANGELOG.md

@@ -24,13 +24,21 @@ All notable changes to this project will be documented in this file. Take a look
 
 ### Changed
 
+* Readium resources are now prefixed with `readium_`. Take care of updating any overridden resource by following [the migration guide](docs/migration-guide.md#300).
+
 #### Navigator
 
 * `EpubNavigatorFragment.firstVisibleElementLocator()` now returns the first *block* element that is visible on the screen, even if it starts on previous pages.
     * This is used to make sure the user will not miss any context when restoring a TTS session in the middle of a resource.
 * The `VisualNavigator`'s drag and tap listener events are moved to a new `addInputListener()` API.
 * The new `DirectionalNavigationAdapter` component replaces `EdgeTapNavigation`, helping you turn pages with the arrow and space keyboard keys, or taps on the edge of the screen.
 
+### Deprecated
+
+#### Navigator
+
+* All the navigator `Activity` are deprecated in favor of the `Fragment` variants.
+
 ### Fixed
 
 #### Navigator

docs/migration-guide.md

@@ -29,6 +29,52 @@ dependencies {
 }
 ```
 
+### All resources now have the prefix `readium_`.
+
+To avoid conflicts when merging your app resources, all resources declared in the Readium toolkit now have the prefix `readium_`. This means that you must rename any layouts or strings you have overridden. Here is a comprehensive list of the changes.
+
+#### Layouts
+
+| Deprecated                  | New                                           |
+|-----------------------------|-----------------------------------------------|
+| `activity_r2_viewpager`     | `readium_navigator_viewpager`                 |
+| `fragment_fxllayout_double` | `readium_navigator_fragment_fxllayout_double` |
+| `fragment_fxllayout_single` | `readium_navigator_fragment_fxllayout_single` |
+| `popup_footnote`            | `readium_navigator_popup_footnote`            |
+| `r2_lcp_auth_dialog`        | `readium_lcp_auth_dialog`                     |
+| `viewpager_fragment_cbz`    | `readium_navigator_viewpager_fragment_cbz`    |
+| `viewpager_fragment_epub`   | `readium_navigator_viewpager_fragment_epub`   |
+
+#### Dimensions
+
+| Deprecated                           | New                                       |
+|--------------------------------------|-------------------------------------------|
+| `r2_navigator_epub_vertical_padding` | `readium_navigator_epub_vertical_padding` |
+
+#### Strings
+
+| Deprecated                                  | New                                              |
+|---------------------------------------------|--------------------------------------------------|
+| `r2_lcp_dialog_cancel`                      | `readium_lcp_dialog_cancel`                      |
+| `r2_lcp_dialog_continue`                    | `readium_lcp_dialog_continue`                    |
+| `r2_lcp_dialog_forgotPassphrase`            | `readium_lcp_dialog_forgotPassphrase`            |
+| `r2_lcp_dialog_help`                        | `readium_lcp_dialog_help`                        |
+| `r2_lcp_dialog_prompt`                      | `readium_lcp_dialog_prompt`                      |
+| `r2_lcp_dialog_reason_invalidPassphrase`    | `readium_lcp_dialog_reason_invalidPassphrase`    |
+| `r2_lcp_dialog_reason_passphraseNotFound`   | `readium_lcp_dialog_reason_passphraseNotFound`   |
+| `r2_lcp_dialog_support_mail`                | `readium_lcp_dialog_support_mail`                |
+| `r2_lcp_dialog_support_phone`               | `readium_lcp_dialog_support_phone`               |
+| `r2_lcp_dialog_support_web`                 | `readium_lcp_dialog_support_web`                 |
+| `r2_media_notification_channel_description` | `readium_media_notification_channel_description` |
+| `r2_media_notification_channel_name`        | `readium_media_notification_channel_name`        |
+
+#### Drawables
+
+| Deprecated                              | New                                          |
+|-----------------------------------------|----------------------------------------------|
+| `r2_media_notification_fastforward.xml` | `readium_media_notification_fastforward.xml` |
+| `r2_media_notification_rewind.xml`      | `readium_media_notification_rewind.xml`      |
+
 ### Publication assets
 
 In most cases, you no longer need to manually create a `PublicationAsset` to open a publication with

readium/adapters/pdfium/build.gradle.kts

@@ -40,6 +40,10 @@ android {
     namespace = "org.readium.adapters.pdfium"
 }
 
+kotlin {
+    explicitApi()
+}
+
 rootProject.ext["publish.artifactId"] = "readium-adapter-pdfium"
 apply(from = "$rootDir/scripts/publish-module.gradle")
 

readium/adapters/pdfium/pdfium-document/build.gradle.kts

@@ -43,6 +43,10 @@ android {
     namespace = "org.readium.adapters.pdfium.document"
 }
 
+kotlin {
+    explicitApi()
+}
+
 rootProject.ext["publish.artifactId"] = "readium-adapter-pdfium-document"
 apply(from = "$rootDir/scripts/publish-module.gradle")
 

readium/adapters/pdfium/pdfium-document/src/main/java/org/readium/adapters/pdfium/document/PdfiumDocument.kt

@@ -15,7 +15,7 @@ import java.io.File
 import kotlin.reflect.KClass
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
-import org.readium.r2.shared.PdfSupport
+import org.readium.r2.shared.InternalReadiumApi
 import org.readium.r2.shared.error.getOrThrow
 import org.readium.r2.shared.extensions.md5
 import org.readium.r2.shared.extensions.tryOrNull
@@ -25,10 +25,9 @@ import org.readium.r2.shared.util.pdf.PdfDocumentFactory
 import org.readium.r2.shared.util.use
 import timber.log.Timber
 
-@OptIn(PdfSupport::class)
-class PdfiumDocument(
-    val core: PdfiumCore,
-    val document: _PdfiumDocument,
+public class PdfiumDocument(
+    @InternalReadiumApi public val core: PdfiumCore,
+    @InternalReadiumApi public val document: _PdfiumDocument,
     override val identifier: String?,
     override val pageCount: Int
 ) : PdfDocument {
@@ -69,19 +68,17 @@ class PdfiumDocument(
 
     override suspend fun close() {}
 
-    companion object
+    public companion object
 }
 
-@OptIn(PdfSupport::class)
 private fun _PdfiumDocument.Bookmark.toOutlineNode(): PdfDocument.OutlineNode =
     PdfDocument.OutlineNode(
         title = title,
         pageNumber = pageIdx.toInt() + 1,
         children = children.map { it.toOutlineNode() }
     )
 
-@OptIn(PdfSupport::class)
-class PdfiumDocumentFactory(context: Context) : PdfDocumentFactory<PdfiumDocument> {
+public class PdfiumDocumentFactory(context: Context) : PdfDocumentFactory<PdfiumDocument> {
 
     override val documentType: KClass<PdfiumDocument> = PdfiumDocument::class
 

readium/adapters/pdfium/pdfium-navigator/build.gradle.kts

@@ -44,6 +44,10 @@ android {
     namespace = "org.readium.adapters.pdfium.navigator"
 }
 
+kotlin {
+    explicitApi()
+}
+
 rootProject.ext["publish.artifactId"] = "readium-adapter-pdfium-navigator"
 apply(from = "$rootDir/scripts/publish-module.gradle")
 

readium/adapters/pdfium/pdfium-navigator/src/main/java/org/readium/adapters/pdfium/navigator/PdfiumDefaults.kt

@@ -17,7 +17,7 @@ import org.readium.r2.shared.ExperimentalReadiumApi
  * @see PdfiumPreferences
  */
 @ExperimentalReadiumApi
-data class PdfiumDefaults(
+public data class PdfiumDefaults(
     val pageSpacing: Double? = null,
     val readingProgression: ReadingProgression? = null,
 )

readium/adapters/pdfium/pdfium-navigator/src/main/java/org/readium/adapters/pdfium/navigator/PdfiumDocumentFragment.kt

@@ -27,7 +27,7 @@ import org.readium.r2.shared.resource.Resource
 import timber.log.Timber
 
 @ExperimentalReadiumApi
-class PdfiumDocumentFragment internal constructor(
+public class PdfiumDocumentFragment internal constructor(
     private val publication: Publication,
     private val link: Link,
     private val initialPageIndex: Int,
@@ -36,9 +36,9 @@ class PdfiumDocumentFragment internal constructor(
     private val navigatorListener: PdfDocumentFragment.Listener?
 ) : PdfDocumentFragment<PdfiumSettings>() {
 
-    interface Listener {
+    public interface Listener {
         /** Called when configuring [PDFView]. */
-        fun onConfigurePdfView(configurator: PDFView.Configurator) {}
+        public fun onConfigurePdfView(configurator: PDFView.Configurator) {}
     }
 
     override var settings: PdfiumSettings = settings

readium/adapters/pdfium/pdfium-navigator/src/main/java/org/readium/adapters/pdfium/navigator/PdfiumEngineProvider.kt

@@ -21,12 +21,12 @@ import org.readium.r2.shared.publication.Publication
  * the navigator for some preferences.
  */
 @ExperimentalReadiumApi
-class PdfiumEngineProvider(
+public class PdfiumEngineProvider(
     private val listener: PdfiumDocumentFragment.Listener? = null,
     private val defaults: PdfiumDefaults = PdfiumDefaults()
 ) : PdfEngineProvider<PdfiumSettings, PdfiumPreferences, PdfiumPreferencesEditor> {
 
-    override suspend fun createDocumentFragment(input: PdfDocumentFragmentInput<PdfiumSettings>) =
+    override suspend fun createDocumentFragment(input: PdfDocumentFragmentInput<PdfiumSettings>): PdfiumDocumentFragment =
         PdfiumDocumentFragment(
             publication = input.publication,
             link = input.link,

readium/adapters/pdfium/pdfium-navigator/src/main/java/org/readium/adapters/pdfium/navigator/PdfiumPreferences.kt

@@ -23,7 +23,7 @@ import org.readium.r2.shared.ExperimentalReadiumApi
  */
 @ExperimentalReadiumApi
 @Serializable
-data class PdfiumPreferences(
+public data class PdfiumPreferences(
     val fit: Fit? = null,
     val pageSpacing: Double? = null,
     val readingProgression: ReadingProgression? = null,
@@ -35,7 +35,7 @@ data class PdfiumPreferences(
         require(pageSpacing == null || pageSpacing >= 0)
     }
 
-    override operator fun plus(other: PdfiumPreferences) =
+    override operator fun plus(other: PdfiumPreferences): PdfiumPreferences =
         PdfiumPreferences(
             fit = other.fit ?: fit,
             pageSpacing = other.pageSpacing ?: pageSpacing,

readium/adapters/pdfium/pdfium-navigator/src/main/java/org/readium/adapters/pdfium/navigator/PdfiumPreferencesEditor.kt

@@ -19,7 +19,7 @@ import org.readium.r2.shared.publication.Metadata
  * or ranges.
  */
 @ExperimentalReadiumApi
-class PdfiumPreferencesEditor internal constructor(
+public class PdfiumPreferencesEditor internal constructor(
     initialPreferences: PdfiumPreferences,
     publicationMetadata: Metadata,
     defaults: PdfiumDefaults,
@@ -49,7 +49,7 @@ class PdfiumPreferencesEditor internal constructor(
     /**
      * Indicates how pages should be laid out within the viewport.
      */
-    val fit: EnumPreference<Fit> =
+    public val fit: EnumPreference<Fit> =
         EnumPreferenceDelegate(
             getValue = { preferences.fit },
             getEffectiveValue = { state.settings.fit },
@@ -61,7 +61,7 @@ class PdfiumPreferencesEditor internal constructor(
     /**
      * Space between pages in dp.
      */
-    val pageSpacing: RangePreference<Double> =
+    public val pageSpacing: RangePreference<Double> =
         RangePreferenceDelegate(
             getValue = { preferences.pageSpacing },
             getEffectiveValue = { state.settings.pageSpacing },
@@ -75,7 +75,7 @@ class PdfiumPreferencesEditor internal constructor(
     /**
      * Direction of the horizontal progression across pages.
      */
-    val readingProgression: EnumPreference<ReadingProgression> =
+    public val readingProgression: EnumPreference<ReadingProgression> =
         EnumPreferenceDelegate(
             getValue = { preferences.readingProgression },
             getEffectiveValue = { state.settings.readingProgression },
@@ -87,7 +87,7 @@ class PdfiumPreferencesEditor internal constructor(
     /**
      * Indicates the axis along which pages should be laid out in scroll mode.
      */
-    val scrollAxis: EnumPreference<Axis> =
+    public val scrollAxis: EnumPreference<Axis> =
         EnumPreferenceDelegate(
             getValue = { preferences.scrollAxis },
             getEffectiveValue = { state.settings.scrollAxis },

readium/adapters/pdfium/pdfium-navigator/src/main/java/org/readium/adapters/pdfium/navigator/PdfiumPreferencesFilters.kt

@@ -13,7 +13,7 @@ import org.readium.r2.shared.ExperimentalReadiumApi
  * Suggested filter to keep only shared [PdfiumPreferences].
  */
 @ExperimentalReadiumApi
-object PdfiumSharedPreferencesFilter : PreferencesFilter<PdfiumPreferences> {
+public object PdfiumSharedPreferencesFilter : PreferencesFilter<PdfiumPreferences> {
 
     override fun filter(preferences: PdfiumPreferences): PdfiumPreferences =
         preferences.copy(
@@ -25,7 +25,7 @@ object PdfiumSharedPreferencesFilter : PreferencesFilter<PdfiumPreferences> {
  * Suggested filter to keep only publication-specific [PdfiumPreferences].
  */
 @ExperimentalReadiumApi
-object PdfiumPublicationPreferencesFilter : PreferencesFilter<PdfiumPreferences> {
+public object PdfiumPublicationPreferencesFilter : PreferencesFilter<PdfiumPreferences> {
 
     override fun filter(preferences: PdfiumPreferences): PdfiumPreferences =
         PdfiumPreferences(

readium/adapters/pdfium/pdfium-navigator/src/main/java/org/readium/adapters/pdfium/navigator/PdfiumPreferencesSerializer.kt

@@ -14,7 +14,7 @@ import org.readium.r2.shared.ExperimentalReadiumApi
  * JSON serializer of [PdfiumPreferences].
  */
 @ExperimentalReadiumApi
-class PdfiumPreferencesSerializer : PreferencesSerializer<PdfiumPreferences> {
+public class PdfiumPreferencesSerializer : PreferencesSerializer<PdfiumPreferences> {
 
     override fun serialize(preferences: PdfiumPreferences): String =
         Json.encodeToString(PdfiumPreferences.serializer(), preferences)

readium/adapters/pdfium/pdfium-navigator/src/main/java/org/readium/adapters/pdfium/navigator/PdfiumSettings.kt

@@ -15,7 +15,7 @@ import org.readium.r2.shared.ExperimentalReadiumApi
  *  @see PdfiumPreferences
  */
 @ExperimentalReadiumApi
-data class PdfiumSettings(
+public data class PdfiumSettings(
     val fit: Fit,
     val pageSpacing: Double,
     val readingProgression: ReadingProgression,

readium/adapters/pspdfkit/build.gradle.kts

@@ -40,6 +40,10 @@ android {
     namespace = "org.readium.adapters.pspdfkit"
 }
 
+kotlin {
+    explicitApi()
+}
+
 rootProject.ext["publish.artifactId"] = "readium-adapter-pspdfkit"
 apply(from = "$rootDir/scripts/publish-module.gradle")
 

readium/adapters/pspdfkit/pspdfkit-document/build.gradle.kts

@@ -43,6 +43,10 @@ android {
     namespace = "org.readium.adapters.pspdfkit.document"
 }
 
+kotlin {
+    explicitApi()
+}
+
 rootProject.ext["publish.artifactId"] = "readium-adapter-pspdfkit-document"
 apply(from = "$rootDir/scripts/publish-module.gradle")
 

readium/adapters/pspdfkit/pspdfkit-document/src/main/java/org/readium/adapters/pspdfkit/document/PsPdfKitDocument.kt

@@ -25,7 +25,7 @@ import org.readium.r2.shared.util.pdf.PdfDocument
 import org.readium.r2.shared.util.pdf.PdfDocumentFactory
 import timber.log.Timber
 
-class PsPdfKitDocumentFactory(context: Context) : PdfDocumentFactory<PsPdfKitDocument> {
+public class PsPdfKitDocumentFactory(context: Context) : PdfDocumentFactory<PsPdfKitDocument> {
     private val context = context.applicationContext
 
     override val documentType: KClass<PsPdfKitDocument> = PsPdfKitDocument::class
@@ -42,8 +42,8 @@ class PsPdfKitDocumentFactory(context: Context) : PdfDocumentFactory<PsPdfKitDoc
         }
 }
 
-class PsPdfKitDocument(
-    val document: _PsPdfKitDocument
+public class PsPdfKitDocument(
+    public val document: _PsPdfKitDocument
 ) : PdfDocument {
 
     // FIXME: Doesn't seem to be exposed by PSPDFKit.

readium/adapters/pspdfkit/pspdfkit-document/src/main/java/org/readium/adapters/pspdfkit/document/ResourceDataProvider.kt

@@ -16,7 +16,7 @@ import org.readium.r2.shared.resource.Resource
 import org.readium.r2.shared.util.isLazyInitialized
 import timber.log.Timber
 
-class ResourceDataProvider(
+internal class ResourceDataProvider(
     resource: Fetcher.Resource,
     private val onResourceError: (Resource.Exception) -> Unit = { Timber.e(it) }
 ) : DataProvider {

readium/adapters/pspdfkit/pspdfkit-navigator/build.gradle.kts

@@ -44,6 +44,10 @@ android {
     namespace = "org.readium.adapters.pspdfkit.navigator"
 }
 
+kotlin {
+    explicitApi()
+}
+
 rootProject.ext["publish.artifactId"] = "readium-adapter-pspdfkit-navigator"
 apply(from = "$rootDir/scripts/publish-module.gradle")
 

readium/adapters/pspdfkit/pspdfkit-navigator/src/main/java/org/readium/adapters/pspdfkit/navigator/PsPdfKitDefaults.kt

@@ -18,7 +18,7 @@ import org.readium.r2.shared.ExperimentalReadiumApi
  * @see PsPdfKitPreferences
  */
 @ExperimentalReadiumApi
-data class PsPdfKitDefaults(
+public data class PsPdfKitDefaults(
     val offsetFirstPage: Boolean? = null,
     val pageSpacing: Double? = null,
     val readingProgression: ReadingProgression? = null,

readium/adapters/pspdfkit/pspdfkit-navigator/src/main/java/org/readium/adapters/pspdfkit/navigator/PsPdfKitEngineProvider.kt

@@ -26,7 +26,7 @@ import org.readium.r2.shared.util.pdf.cachedIn
  * the navigator for some preferences.
  */
 @ExperimentalReadiumApi
-class PsPdfKitEngineProvider(
+public class PsPdfKitEngineProvider(
     private val context: Context,
     private val defaults: PsPdfKitDefaults = PsPdfKitDefaults()
 ) : PdfEngineProvider<PsPdfKitSettings, PsPdfKitPreferences, PsPdfKitPreferencesEditor> {

readium/adapters/pspdfkit/pspdfkit-navigator/src/main/java/org/readium/adapters/pspdfkit/navigator/PsPdfKitPreferences.kt

@@ -23,7 +23,7 @@ import org.readium.r2.shared.ExperimentalReadiumApi
  */
 @ExperimentalReadiumApi
 @Serializable
-data class PsPdfKitPreferences(
+public data class PsPdfKitPreferences(
     val fit: Fit? = null,
     val offsetFirstPage: Boolean? = null,
     val pageSpacing: Double? = null,
@@ -38,7 +38,7 @@ data class PsPdfKitPreferences(
         require(pageSpacing == null || pageSpacing >= 0)
     }
 
-    override operator fun plus(other: PsPdfKitPreferences) =
+    override operator fun plus(other: PsPdfKitPreferences): PsPdfKitPreferences =
         PsPdfKitPreferences(
             fit = other.fit ?: fit,
             offsetFirstPage = other.offsetFirstPage ?: offsetFirstPage,