Merge branch 'v3' into documentation

Author: mickael-menu

.github/workflows/checks.yml

@@ -7,17 +7,17 @@ on:
 
 env:
   platform: ${{ 'iOS Simulator' }}
-  device: ${{ 'iPhone 12' }}
+  device: ${{ 'iPhone 15' }}
   commit_sha: ${{ github.sha }}
+  DEVELOPER_DIR: /Applications/Xcode_15.0.1.app/Contents/Developer
 
 jobs:
   build:
     name: Build
-    runs-on: macos-12
+    runs-on: macos-13
     if: ${{ !github.event.pull_request.draft }}
     env:
       scheme: ${{ 'Readium-Package' }}
-      DEVELOPER_DIR: /Applications/Xcode_13.4.1.app/Contents/Developer
 
     steps:
       - name: Checkout
@@ -42,7 +42,7 @@ jobs:
 
   lint:
     name: Lint
-    runs-on: macos-12
+    runs-on: macos-13
     if: ${{ !github.event.pull_request.draft }}
     env:
       scripts: ${{ 'Sources/Navigator/EPUB/Scripts' }}
@@ -76,7 +76,7 @@ jobs:
 
   int-dev:
     name: Integration (Local)
-    runs-on: macos-12
+    runs-on: macos-13
     if: ${{ !github.event.pull_request.draft }}
     defaults:
       run:
@@ -98,7 +98,7 @@ jobs:
 
   int-spm:
     name: Integration (Swift Package Manager)
-    runs-on: macos-12
+    runs-on: macos-13
     if: ${{ !github.event.pull_request.draft }}
     defaults:
       run:
@@ -126,7 +126,7 @@ jobs:
 
   int-carthage:
     name: Integration (Carthage)
-    runs-on: macos-12
+    runs-on: macos-13
     if: ${{ !github.event.pull_request.draft }}
     defaults:
       run:
@@ -157,7 +157,7 @@ jobs:
   int-cocoapods:
     name: Integration (CocoaPods)
     if: github.event_name == 'push'
-    runs-on: macos-12
+    runs-on: macos-13
     defaults:
       run:
         working-directory: TestApp

CHANGELOG.md

@@ -4,7 +4,22 @@ All notable changes to this project will be documented in this file. Take a look
 
 **Warning:** Features marked as *alpha* may change or be removed in a future release without notice. Use with caution.
 
-<!-- ## [Unreleased] -->
+## [Unreleased]
+
+### Changed
+
+* The `R2Shared`, `R2Streamer` and `R2Navigator` packages are now called `ReadiumShared`, `ReadiumStreamer` and `ReadiumNavigator`.
+* Many APIs now expect one of the new URL types (`RelativeURL`, `AbsoluteURL`, `HTTPURL` and `FileURL`). This is helpful because:
+    * It validates at compile time that we provide a URL that is supported.
+    * The API's capabilities are better documented, e.g. a download API could look like this : `download(url: HTTPURL) -> FileURL`. 
+
+#### Shared
+
+* `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](Documentation/Migration%20Guide.md) for guidance.
+* Links are not resolved to the `self` URL of a manifest anymore. However, you can still normalize the HREFs yourselves by calling `Manifest.normalizeHREFsToSelf()`.
+* `Publication.localizedTitle` is now optional, as we cannot guarantee a publication will always have a title.
+
 
 ## [2.7.0]
 

Documentation/Guides/Navigator/Preferences.md

@@ -161,7 +161,7 @@ This stateless view displays the actual preferences for a fixed-layout publicati
 @ViewBuilder func fixedLayoutUserPreferences(
     commit: @escaping () -> Void,
     scroll: AnyPreference<Bool>? = nil,
-    fit: AnyEnumPreference<R2Navigator.Fit>? = nil,
+    fit: AnyEnumPreference<ReadiumNavigator.Fit>? = nil,
     pageSpacing: AnyRangePreference<Double>? = nil
 ) -> some View {
     if let scroll = scroll {

Documentation/Migration Guide.md

@@ -2,6 +2,73 @@
 
 All migration steps necessary in reading apps to upgrade to major versions of the Swift Readium toolkit will be documented in this file.
 
+## Unreleased
+
+### R2 prefix dropped
+
+The `R2` prefix is now deprecated. The `R2Shared`, `R2Streamer` and `R2Navigator` packages were renamed as `ReadiumShared`, `ReadiumStreamer` and `ReadiumNavigator`.
+
+You will need to update your imports, as well as the dependencies you include in your project:
+
+* Swift Package Manager: There's nothing to do.
+* Carthage:
+    * Update the Carthage dependencies and make sure the new `ReadiumShared.xcframework`, `ReadiumStreamer.xcframework` and `ReadiumNavigator.xcframework` were built.
+    * Replace the old frameworks with the new ones in your project.
+* CocoaPods:
+    * Update the `pod` statements in your `Podfile` with the following, before running `pod install`:
+        ```
+        pod 'ReadiumShared', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/3.0.0/Support/CocoaPods/ReadiumShared.podspec'
+        pod 'ReadiumStreamer', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/3.0.0/Support/CocoaPods/ReadiumStreamer.podspec'
+        pod 'ReadiumNavigator', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/3.0.0/Support/CocoaPods/ReadiumNavigator.podspec'
+        ```
+
+### Migration of HREFs and Locators (bookmarks, annotations, etc.)
+
+ :warning: This requires a database migration in your application, if you were persisting `Locator` objects.
+
+ In Readium v2.x, a `Link` or `Locator`'s `href` could be either:
+
+ * a valid absolute URL for a streamed publication, e.g. `https://domain.com/isbn/dir/my%20chapter.html`,
+ * a percent-decoded path for a local archive such as an EPUB, e.g. `/dir/my chapter.html`.
+     * Note that it was relative to the root of the archive (`/`).
+
+ 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`.
+
+ * `https://domain.com/isbn/dir/my%20chapter.html` is left unchanged, as it was already a valid URL.
+ * `/dir/my chapter.html` becomes the relative URL path `dir/my%20chapter.html`
+     * We dropped the `/` prefix to avoid issues when resolving to a base URL.
+     * Special characters are percent-encoded.
+
+ **You must migrate the HREFs or Locators stored in your database** when upgrading to Readium 3. To assist you, two helpers are provided: `AnyURL(legacyHREF:)` and `Locator(legacyJSONString:)`.
+
+ Here's an example of a [GRDB migration](https://swiftpackageindex.com/groue/grdb.swift/master/documentation/grdb/migrations) that can serve as inspiration:
+
+ ```swift
+ migrator.registerMigration("normalizeHREFs") { db in
+    let normalizedRows: [(id: Int, href: String, locator: String)] =
+        try Row.fetchAll(db, sql: "SELECT id, href, locator FROM bookmarks")
+            .compactMap { row in
+                guard
+                    let normalizedHREF = AnyURL(legacyHREF: row["href"])?.string,
+                    let normalizedLocator = try Locator(legacyJSONString: row["locator"])?.jsonString
+                else {
+                    return nil
+                }
+                return (row["id"], normalizedHREF, normalizedLocator)
+            }
+            
+    let updateStmt = try db.makeStatement(sql: "UPDATE bookmarks SET href = :href, locator = :locator WHERE id = :id")
+    for (id, href, locator) in normalizedRows {
+        try updateStmt.execute(arguments: [
+            "id": id,
+            "href": href
+            "locator": locator
+        ])
+    }
+}
+```
+
+
 ## 2.7.0
 
 ### `AudioNavigator` is now stable
@@ -56,7 +123,7 @@ Instead, the EPUB, PDF and CBZ navigators expect an instance of `HTTPServer` upo
 You can implement your own HTTP server using a third-party library. But the easiest way to migrate is to use the one provided in the new Readium package `ReadiumAdapterGCDWebServer`.
 
 ```swift
-import R2Navigator
+import ReadiumNavigator
 import ReadiumAdapterGCDWebServer
 
 let navigator = try EPUBNavigatorViewController(
@@ -167,15 +234,15 @@ Then, rebuild the libraries using `carthage update --platform ios --use-xcframew
 If you are using CocoaPods, you will need to update the URL to the Podspecs in your `Podfile`:
 
 ```diff
-+  pod 'R2Shared', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.2.0/Support/CocoaPods/ReadiumShared.podspec'
-+  pod 'R2Streamer', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.2.0/Support/CocoaPods/ReadiumStreamer.podspec'
-+  pod 'R2Navigator', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.2.0/Support/CocoaPods/ReadiumNavigator.podspec'
++  pod 'ReadiumShared', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.2.0/Support/CocoaPods/ReadiumShared.podspec'
++  pod 'ReadiumStreamer', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.2.0/Support/CocoaPods/ReadiumStreamer.podspec'
++  pod 'ReadiumNavigator', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.2.0/Support/CocoaPods/ReadiumNavigator.podspec'
 +  pod 'ReadiumOPDS', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.2.0/Support/CocoaPods/ReadiumOPDS.podspec'
 +  pod 'ReadiumLCP', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.2.0/Support/CocoaPods/ReadiumLCP.podspec'
 
--  pod 'R2Shared', podspec: 'https://raw.githubusercontent.com/readium/r2-shared-swift/2.2.0/R2Shared.podspec'
--  pod 'R2Streamer', podspec: 'https://raw.githubusercontent.com/readium/r2-streamer-swift/2.2.0/R2Streamer.podspec'
--  pod 'R2Navigator', podspec: 'https://raw.githubusercontent.com/readium/r2-navigator-swift/2.2.0/R2Navigator.podspec'
+-  pod 'ReadiumShared', podspec: 'https://raw.githubusercontent.com/readium/r2-shared-swift/2.2.0/ReadiumShared.podspec'
+-  pod 'ReadiumStreamer', podspec: 'https://raw.githubusercontent.com/readium/r2-streamer-swift/2.2.0/ReadiumStreamer.podspec'
+-  pod 'ReadiumNavigator', podspec: 'https://raw.githubusercontent.com/readium/r2-navigator-swift/2.2.0/ReadiumNavigator.podspec'
 -  pod 'ReadiumOPDS', podspec: 'https://raw.githubusercontent.com/readium/r2-opds-swift/2.2.0/ReadiumOPDS.podspec'
 -  pod 'ReadiumLCP', podspec: 'https://raw.githubusercontent.com/readium/r2-lcp-swift/2.2.0/ReadiumLCP.podspec'
 ```
@@ -275,7 +342,7 @@ Migrating a project to XCFrameworks is [explained on Carthage's repository](http
 
 #### Troubleshooting
 
-If after migrating to XCFrameworks you experience some build issues like **Could not find module 'R2Shared' for target 'X'**, try building the `r2-shared-swift` target with Xcode manually, before building your app. If you know of a better way to handle this, [please share it with the community](https://github.com/readium/r2-testapp-swift/issues/new).
+If after migrating to XCFrameworks you experience some build issues like **Could not find module 'ReadiumShared' for target 'X'**, try building the `r2-shared-swift` target with Xcode manually, before building your app. If you know of a better way to handle this, [please share it with the community](https://github.com/readium/r2-testapp-swift/issues/new).
 
 ### LCP
 

Makefile

@@ -18,16 +18,22 @@ scripts:
 	@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); \
+	rm -rf "node_modules"; \
 	corepack install; \
 	pnpm install --frozen-lockfile; \
 	pnpm run format; \
 	pnpm run lint; \
 	pnpm run bundle
 
+.PHONY: update-scripts
+update-scripts:
+	@which corepack >/dev/null 2>&1 || (echo "ERROR: corepack is required, please install it first\nhttps://pnpm.io/installation#using-corepack"; exit 1)
+	pnpm install --dir "$(SCRIPTS_PATH)"
+
 .PHONY: test
 test:
-	# To limit to a particular test suite: -only-testing:R2SharedTests
-	xcodebuild test -scheme "Readium-Package" -destination "platform=iOS Simulator,name=iPhone 12" | xcbeautify -q
+	# To limit to a particular test suite: -only-testing:ReadiumSharedTests
+	xcodebuild test -scheme "Readium-Package" -destination "platform=iOS Simulator,name=iPhone 15" | xcbeautify -q
 
 .PHONY: lint-format
 lint-format:

Package.swift

@@ -12,9 +12,9 @@ let package = Package(
     defaultLocalization: "en",
     platforms: [.iOS(.v11)],
     products: [
-        .library(name: "R2Shared", targets: ["R2Shared"]),
-        .library(name: "R2Streamer", targets: ["R2Streamer"]),
-        .library(name: "R2Navigator", targets: ["R2Navigator"]),
+        .library(name: "ReadiumShared", targets: ["ReadiumShared"]),
+        .library(name: "ReadiumStreamer", targets: ["ReadiumStreamer"]),
+        .library(name: "ReadiumNavigator", targets: ["ReadiumNavigator"]),
         .library(name: "ReadiumOPDS", targets: ["ReadiumOPDS"]),
         .library(name: "ReadiumLCP", targets: ["ReadiumLCP"]),
 
@@ -37,7 +37,7 @@ let package = Package(
     ],
     targets: [
         .target(
-            name: "R2Shared",
+            name: "ReadiumShared",
             dependencies: ["ReadiumInternal", "Fuzi", "SwiftSoup", "Zip"],
             path: "Sources/Shared",
             exclude: [
@@ -53,42 +53,42 @@ let package = Package(
             ]
         ),
         .testTarget(
-            name: "R2SharedTests",
-            dependencies: ["R2Shared"],
+            name: "ReadiumSharedTests",
+            dependencies: ["ReadiumShared"],
             path: "Tests/SharedTests",
             resources: [
                 .copy("Fixtures"),
             ]
         ),
 
         .target(
-            name: "R2Streamer",
+            name: "ReadiumStreamer",
             dependencies: [
                 "CryptoSwift",
                 "Fuzi",
                 .product(name: "ReadiumGCDWebServer", package: "GCDWebServer"),
                 "Zip",
-                "R2Shared",
+                "ReadiumShared",
             ],
             path: "Sources/Streamer",
             resources: [
                 .copy("Assets"),
             ]
         ),
         .testTarget(
-            name: "R2StreamerTests",
-            dependencies: ["R2Streamer"],
+            name: "ReadiumStreamerTests",
+            dependencies: ["ReadiumStreamer"],
             path: "Tests/StreamerTests",
             resources: [
                 .copy("Fixtures"),
             ]
         ),
 
         .target(
-            name: "R2Navigator",
+            name: "ReadiumNavigator",
             dependencies: [
                 "ReadiumInternal",
-                "R2Shared",
+                "ReadiumShared",
                 "DifferenceKit",
                 "SwiftSoup",
             ],
@@ -102,16 +102,16 @@ let package = Package(
             ]
         ),
         .testTarget(
-            name: "R2NavigatorTests",
-            dependencies: ["R2Navigator"],
+            name: "ReadiumNavigatorTests",
+            dependencies: ["ReadiumNavigator"],
             path: "Tests/NavigatorTests"
         ),
 
         .target(
             name: "ReadiumOPDS",
             dependencies: [
                 "Fuzi",
-                "R2Shared",
+                "ReadiumShared",
             ],
             path: "Sources/OPDS"
         ),
@@ -129,7 +129,7 @@ let package = Package(
             dependencies: [
                 "CryptoSwift",
                 "ZIPFoundation",
-                "R2Shared",
+                "ReadiumShared",
                 .product(name: "SQLite", package: "SQLite.swift"),
             ],
             path: "Sources/LCP",
@@ -152,7 +152,7 @@ let package = Package(
             name: "ReadiumAdapterGCDWebServer",
             dependencies: [
                 .product(name: "ReadiumGCDWebServer", package: "GCDWebServer"),
-                "R2Shared",
+                "ReadiumShared",
             ],
             path: "Sources/Adapters/GCDWebServer"
         ),