Merge pull request readium#442 from readium/v3

.github/workflows/checks.yml

@@ -13,11 +13,11 @@ jobs:
  if: ${{ !github.event.pull_request.draft }}
  steps:
  - name: Checkout
- uses: actions/checkout@v2
- - name: Set up JDK 11
- uses: actions/setup-java@v2
+ uses: actions/checkout@v3
+ - name: Set up JDK 17
+ uses: actions/setup-java@v3
  with:
- java-version: '11'
+ java-version: '17'
  distribution: 'adopt'
  - name: Build
  run: ./gradlew clean build -x test -x ktlintMainSourceSetCheck
@@ -30,11 +30,11 @@ jobs:
  if: ${{ !github.event.pull_request.draft }}
  steps:
  - name: Checkout
- uses: actions/checkout@v2
- - name: Set up JDK 11
- uses: actions/setup-java@v2
+ uses: actions/checkout@v3
+ - name: Set up JDK 17
+ uses: actions/setup-java@v3
  with:
- java-version: '11'
+ java-version: '17'
  distribution: 'adopt'
  - name: Lint
  run: ./gradlew ktlintCheck
@@ -43,22 +43,29 @@ jobs:
  name: Lint JavaScript
  runs-on: macos-latest
  if: ${{ !github.event.pull_request.draft }}
- defaults:
- run:
- working-directory: readium/navigator
  env:
- scripts: ${{ 'src/main/assets/_scripts' }}
+ scripts: ${{ 'readium/navigator/src/main/assets/_scripts' }}
  steps:
  - name: Checkout
- uses: actions/checkout@v2
+ uses: actions/checkout@v3
+ - name: Install pnpm
+ uses: pnpm/action-setup@v2
+ with:
+ package_json_file: readium/navigator/src/main/assets/_scripts/package.json
+ run_install: false
+ - name: Setup cache
+ uses: actions/setup-node@v3
+ with:
+ node-version: 20
+ cache: 'pnpm'
+ cache-dependency-path: readium/navigator/src/main/assets/_scripts/pnpm-lock.yaml
  - name: Install dependencies
- run: yarn --cwd "$scripts" install --frozen-lockfile
+ run: pnpm --dir "$scripts" install --frozen-lockfile
  - name: Lint
- run: yarn --cwd "$scripts" run lint
+ run: pnpm --dir "$scripts" run lint
  - name: Check formatting
- run: yarn --cwd "$scripts" run checkformat
- # FIXME: This suddenly stopped working even though the toolchain versions seem identical.
- # - name: Check if bundled scripts are up-to-date
- # run: |
- # make scripts
- # git diff --exit-code --name-only src/main/assets/readium/scripts/*.js
+ run: pnpm --dir "$scripts" run checkformat
+ - name: Check if bundled scripts are up-to-date
+ run: |
+ make scripts
+ git diff --exit-code --name-only src/main/assets/readium/scripts/*.js

.github/workflows/docs.yml

@@ -30,7 +30,7 @@ jobs:
 
  - uses: actions/setup-java@v3
  with:
- java-version: 11
+ java-version: 17
  distribution: 'adopt'
 
  - name: Get current Readium version

.github/workflows/publish.yml

@@ -12,14 +12,14 @@ jobs:
  runs-on: ubuntu-latest
  steps:
  - name: Checkout
- uses: actions/checkout@v2
+ uses: actions/checkout@v3
  with:
  ref: develop
- - name: Set up JDK 11
- uses: actions/setup-java@v2
+ - name: Set up JDK 17
+ uses: actions/setup-java@v3
  with:
  distribution: adopt
- java-version: 11
+ java-version: 17
 
  # Builds the release artifacts of the library
  - name: Release build

.gitignore

@@ -48,6 +48,7 @@ captures/
 .idea/libraries
 .idea/jarRepositories.xml
 .idea/misc.xml
+.idea/migrations.xml
 # Android Studio 3 in .gitignore file.
 .idea/caches
 .idea/modules.xml
@@ -82,4 +83,5 @@ lint/reports/
 docs/readium
 docs/index.md
 docs/package-list
-site/
+site/
+androidTestResultsUserPreferences.xml

CHANGELOG.md

@@ -4,7 +4,68 @@ 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]
+
+:warning: Please consult [the migration guide](docs/migration-guide.md#300-alpha1) to assist you in handling the breaking changes in this latest major release.
+
+### Added
+
+#### Shared
+
+* A new `Format` type was introduced to augment `MediaType` with more precise information about the format specifications of an `Asset`.
+* The `DownloadManager` interface handles HTTP downloads. Components like the `LcpService` rely on it for downloading publications. Readium v3 ships with two implementations:
+ * `ForegroundDownloadManager` uses an `HttpClient` to download files while the app is running.
+ * `AndroidDownloadManager` is built upon [Android's `DownloadManager`](https://developer.android.com/reference/android/app/DownloadManager) to manage HTTP downloads, even when the application is closed. It allows for resuming downloads after losing connection.
+* The default `ZipArchiveOpener` now supports streaming ZIP archives, which enables opening a packaged publication (e.g. EPUB or LCP protected audiobook):
+ * served by a remote HTTP server,
+ * accessed through an Android `ContentProvider`, such as the shared storage.
+
+#### Navigator
+
+* Support for keyboard events in the EPUB, PDF and image navigators. See `VisualNavigator.addInputListener()`.
+
+#### LCP
+
+* You can now stream an LCP protected publication using its LCP License Document. This is useful for example to read a large audiobook without downloading it on the device first.
+* The hash of protected publications is now verified upon download.
+
+### Changed
+
+* :warning: 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. Some resources were removed from the toolkit. Please consult [the migration guide](docs/migration-guide.md#300-alpha1).
+* Most APIs now return an `Error` instance instead of an `Exception` in case of failure, as these objects are not thrown by the toolkit but returned as values
+
+#### Shared
+
+* :warning: To improve the interoperability with other Readium toolkits (in particular the Readium Web Toolkits, which only work in a streaming context) **Readium v3 now generates and expects valid URLs** for `Locator` and `Link`'s `href`. **You must migrate the HREFs or Locators stored in your database**, please consult [the migration guide](docs/migration-guide.md#300-alpha1).
+* `Link.href` and `Locator.href` are now respectively `Href` and `Url` objects. If you still need the string value, you can call `toString()`
+* `MediaType` no longer has static helpers for sniffing it from a file or URL. Instead, you can use an `AssetRetriever` to retrieve the format of a file.
+
+#### Navigator
+
+* Version 3 includes a new component called `DirectionalNavigationAdapter` that replaces `EdgeTapNavigation`. This helper enables users to navigate between pages using arrow and space keys on their keyboard or by tapping the edge of the screen.
+* The `onTap` and `onDrag` events of `VisualNavigator.Listener` have been deprecated. You can now use multiple implementations of `InputListener` with `VisualNavigator.addInputListener()`.
+
+#### Streamer
+
+* The `Streamer` object has been deprecated in favor of components with smaller responsibilities: `AssetRetriever` and `PublicationOpener`.
+
+#### LCP
+
+* `LcpService.acquirePublication()` is deprecated in favor of `LcpService.publicationRetriever()`, which provides greater flexibility thanks to the `DownloadManager`.
+* The way the host view of a `LcpDialogAuthentication` is retrieved was changed to support Android configuration changes.
+
+### Deprecated
+
+* Both the Fuel and Kovenant libraries have been completely removed from the toolkit. With that, several deprecated functions have also been removed.
+
+#### Shared
+
+* The `putPublication` and `getPublication` helpers in `Intent` are deprecated. Now, it is the application's responsibility to pass `Publication` objects between activities and reopen them when necessary.
+
+#### Navigator
+
+* EPUB external links are no longer handled by the navigator. You need to open the link in your own Web View or Chrome Custom Tab.
+
 
 ## [2.4.0]
 
@@ -48,10 +109,35 @@ 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).
+* `Link` and `Locator`'s `href` are normalized as valid URLs to improve interoperability with the Readium Web toolkits.
+ * **You MUST migrate your database if you were persisting HREFs and Locators**. Take a look at [the migration guide](docs/migration-guide.md) for guidance.
+
+#### Shared
+
+* `Publication.localizedTitle` is nullable, as we cannot guarantee that all publication sources offer a title.
+* The `MediaType` sniffing helpers are deprecated in favor of `MediaTypeRetriever` (for media type and file extension hints and raw content) and `AssetRetriever` (for URLs). 
+
 #### 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
+
+#### Shared
+
+* `DefaultHttClient.additionalHeaders` is deprecated. Set all the headers when creating a new `HttpRequest`, or modify outgoing requests in `DefaultHttpClient.Callback.onStartRequest()`.
+
+#### Navigator
+
+* All the navigator `Activity` are deprecated in favor of the `Fragment` variants.
+
+#### Streamer
+
+* The `Fetcher` interface was deprecated in favor of the `Container` one in `readium-shared`.
 
 ### Fixed
 
@@ -63,7 +149,6 @@ All notable changes to this project will be documented in this file. Take a look
 
 * Fixed issue with the TTS starting from the beginning of the chapter instead of the current position.
 
-
 ## [2.3.0]
 
 ### Added

Makefile

@@ -17,7 +17,11 @@ format:
 
 .PHONY: scripts
 scripts:
- yarn --cwd "$(SCRIPTS_PATH)" install --frozen-lockfile
- yarn --cwd "$(SCRIPTS_PATH)" run format
- yarn --cwd "$(SCRIPTS_PATH)" run lint
- yarn --cwd "$(SCRIPTS_PATH)" run bundle
+ @which corepack >/dev/null 2>&1 || (echo "ERROR: corepack is required, please install it first\nhttps://pnpm.io/installation#using-corepack"; exit 1)
+
+ cd $(SCRIPTS_PATH); \
+ corepack install; \
+ pnpm install --frozen-lockfile; \
+ pnpm run format; \
+ pnpm run lint; \
+ pnpm run bundle

README.md

@@ -19,9 +19,12 @@ A [Test App](test-app) demonstrates how to integrate the Readium Kotlin toolkit
 
 ## Minimum Requirements
 
-| Readium | Android min SDK | Android compile SDK | Kotlin compiler | Gradle |
-|---------|-----------------|---------------------|-----------------|--------|
-| latest | 21 | 33 | 1.7.10 | 6.9.3 |
+| Readium | Android min SDK | Android compile SDK | Kotlin compiler (✻) | Gradle (✻) |
+|---------|-----------------|---------------------|---------------------|------------|
+| 3.0.0 | 21 | 34 | 1.9.22 | 8.2.0 |
+| 2.3.0 | 21 | 33 | 1.7.10 | 6.9.3 |
+
+✻ Only required if you integrate Readium as a submodule instead of using Maven Central.
 
 ## Setting Up Readium
 

build.gradle.kts

@@ -12,6 +12,7 @@ plugins {
  id("io.github.gradle-nexus.publish-plugin") apply true
  id("org.jetbrains.dokka") apply true
  id("org.jetbrains.kotlin.android") apply false
+ id("com.google.devtools.ksp") apply false
  id("org.jlleitschuh.gradle.ktlint") apply true
 }
 

docs/guides/index.md

@@ -0,0 +1,9 @@
+# User guides
+
+* [Opening a publication](open-publication.md)
+* [Extracting the content of a publication](content.md)
+* [Supporting PDF documents](pdf.md)
+* [Configuring the Navigator](navigator-preferences.md)
+* [Font families in the EPUB navigator](epub-fonts.md)
+* [Media Navigator](media-navigator.md)
+* [Text-to-speech](tts.md)