Add EPUBNavigatorViewController's viewport (#612)

Author: mickael-menu

CHANGELOG.md

@@ -2,7 +2,14 @@
 
 All notable changes to this project will be documented in this file. Take a look at [the migration guide](docs/Migration%20Guide.md) to upgrade between two major versions.
 
-<!-- ## [Unreleased] -->
+## [Unreleased]
+
+### Added
+
+#### Navigator
+
+* You can now access the `viewport` property of an `EPUBNavigatorViewController` to obtain information about the visible portion of the publication, including the visible positions and reading order indices.
+
 
 ## [3.3.0]
 

Sources/Navigator/Audiobook/AudioNavigator.swift

@@ -194,7 +194,7 @@ public final class AudioNavigator: Navigator, Configurable, AudioSessionUser, Lo
 
     /// Resumes or start the playback.
     public func play() {
-        playTask = Task {
+        playTask = Task { @MainActor in
             AudioSession.shared.start(with: self, isPlaying: false)
 
             if player.currentItem == nil {
@@ -204,7 +204,7 @@ public final class AudioNavigator: Navigator, Configurable, AudioSessionUser, Lo
                     await go(to: link)
                 }
             }
-            await player.playImmediately(atRate: Float(settings.speed))
+            player.playImmediately(atRate: Float(settings.speed))
         }
     }
 

Sources/Navigator/EPUB/Assets/Static/scripts/readium-fixed.js

@@ -95,7 +95,11 @@ final class EPUBFixedSpreadView: EPUBSpreadView {
         }
         // We call this directly on the web view on purpose, because this needs
         // to be executed before the spread is loaded.
-        webView.evaluateJavaScript("spread.load(\(spread.jsonString(forBaseURL: viewModel.publicationBaseURL)));")
+        let spreadJSON = spread.jsonString(
+            forBaseURL: viewModel.publicationBaseURL,
+            readingOrder: viewModel.readingOrder
+        )
+        webView.evaluateJavaScript("spread.load(\(spreadJSON));")
     }
 
     override func spreadDidLoad() async {

Sources/Navigator/EPUB/Assets/Static/scripts/readium-reflowable.js

@@ -11,13 +11,18 @@ import SwiftSoup
 import UIKit
 import WebKit
 
-public protocol EPUBNavigatorDelegate: VisualNavigatorDelegate, SelectableNavigatorDelegate {
+@MainActor public protocol EPUBNavigatorDelegate: VisualNavigatorDelegate, SelectableNavigatorDelegate {
+    /// Called when the viewport is updated.
+    func navigator(_ navigator: EPUBNavigatorViewController, viewportDidChange viewport: EPUBNavigatorViewController.Viewport?)
+
     // MARK: - WebView Customization
 
     func navigator(_ navigator: EPUBNavigatorViewController, setupUserScripts userContentController: WKUserContentController)
 }
 
 public extension EPUBNavigatorDelegate {
+    func navigator(_ navigator: EPUBNavigatorViewController, viewportDidChange viewport: EPUBNavigatorViewController.Viewport?) {}
+
     func navigator(_ navigator: EPUBNavigatorViewController, setupUserScripts userContentController: WKUserContentController) {}
 }
 
@@ -117,6 +122,24 @@ open class EPUBNavigatorViewController: InputObservableViewController,
 
     public weak var delegate: EPUBNavigatorDelegate?
 
+    /// Information about the visible portion of the publication, when rendered.
+    public private(set) var viewport: Viewport? {
+        didSet {
+            if oldValue != viewport {
+                delegate?.navigator(self, viewportDidChange: viewport)
+            }
+        }
+    }
+
+    /// Information about the visible portion of the publication.
+    public struct Viewport: Equatable {
+        /// Indices of the visible reading order resources.
+        public var readingOrderIndices: ClosedRange<[Link].Index>
+
+        /// Range of visible positions.
+        public var positions: ClosedRange<Int>?
+    }
+
     /// Navigation state.
     private enum State: Equatable {
         /// Initializing the navigator.
@@ -488,15 +511,6 @@ open class EPUBNavigatorViewController: InputObservableViewController,
         paginationView?.currentIndex ?? 0
     }
 
-    // Reading order index of the left-most resource in the visible spread.
-    private var currentResourceIndex: Int? {
-        guard spreads.indices.contains(currentSpreadIndex) else {
-            return nil
-        }
-
-        return readingOrder.firstIndexWithHREF(spreads[currentSpreadIndex].left.url())
-    }
-
     private var reloadSpreadsContinuations = [CheckedContinuation<Void, Never>]()
     private var needsReloadSpreads = false
 
@@ -542,8 +556,12 @@ open class EPUBNavigatorViewController: InputObservableViewController,
             spread: viewModel.spreadEnabled
         )
 
-        let initialIndex: Int = {
-            if let href = locator?.href, let foundIndex = self.spreads.firstIndexWithHREF(href) {
+        let initialIndex: ReadingOrder.Index = {
+            if
+                let href = locator?.href,
+                let index = readingOrder.firstIndexWithHREF(href),
+                let foundIndex = self.spreads.firstIndexWithReadingOrderIndex(index)
+            {
                 return foundIndex
             } else {
                 return 0
@@ -561,9 +579,16 @@ open class EPUBNavigatorViewController: InputObservableViewController,
     }
 
     private func loadedSpreadViewForHREF<T: URLConvertible>(_ href: T) -> EPUBSpreadView? {
-        paginationView?.loadedViews
+        guard
+            let loadedViews = paginationView?.loadedViews,
+            let index = readingOrder.firstIndexWithHREF(href)
+        else {
+            return nil
+        }
+
+        return loadedViews
             .compactMap { _, view in view as? EPUBSpreadView }
-            .first { $0.spread.links.firstWithHREF(href) != nil }
+            .first { $0.spread.contains(index: index) }
     }
 
     // MARK: - Navigator
@@ -582,45 +607,64 @@ open class EPUBNavigatorViewController: InputObservableViewController,
         )
     }
 
-    private func computeCurrentLocation() async -> Locator? {
+    private func computeCurrentLocationAndViewport() async -> (Locator?, Viewport?) {
         if case .initializing = state {
             assertionFailure("Cannot update current location when initializing the navigator")
-            return nil
+            return (nil, nil)
         }
 
         // Returns any pending locator to prevent returning invalid locations
         // while loading it.
         if let pendingLocator = state.pendingLocator {
-            return pendingLocator
+            return (pendingLocator, nil)
         }
 
         guard let spreadView = paginationView?.currentView as? EPUBSpreadView else {
-            return nil
+            return (nil, nil)
         }
 
-        let link = spreadView.focusedResource ?? spreadView.spread.leading
+        let index = spreadView.focusedResource ?? spreadView.spread.leading
+        let link = readingOrder[index]
         let href = link.url()
-        let progression = min(max(spreadView.progression(in: href), 0.0), 1.0)
+        let progressionRange = spreadView.progression(in: index)
+        let firstProgression = min(max(progressionRange.lowerBound, 0.0), 1.0)
+        let lastProgression = min(max(progressionRange.upperBound, 0.0), 1.0)
+
+        let location: Locator?
+        var viewport = Viewport(
+            readingOrderIndices: spreadView.spread.readingOrderIndices,
+            positions: nil
+        )
 
         if
             // The positions are not always available, for example a Readium
             // WebPub doesn't have any unless a Publication Positions Web
             // Service is provided
             let index = readingOrder.firstIndexWithHREF(href),
             let positionList = positionsByReadingOrder.getOrNil(index),
-            positionList.count > 0
+            positionList.count > 0,
+            let positionOffset = positionList[0].locations.position
         {
             // Gets the current locator from the positionList, and fill its missing data.
-            let positionIndex = Int(ceil(progression * Double(positionList.count - 1)))
-            return await positionList[positionIndex].copy(
+            let firstPositionIndex = Int(ceil(firstProgression * Double(positionList.count - 1)))
+            let lastPositionIndex = (lastProgression == 1.0)
+                ? positionList.count - 1
+                : max(firstPositionIndex, Int(ceil(lastProgression * Double(positionList.count - 1))) - 1)
+
+            location = await positionList[firstPositionIndex].copy(
                 title: tableOfContentsTitleByHref[equivalent: href],
-                locations: { $0.progression = progression }
+                locations: { $0.progression = firstProgression }
             )
+
+            viewport.positions = (positionOffset + firstPositionIndex) ... (positionOffset + lastPositionIndex)
+
         } else {
-            return await publication.locate(link)?.copy(
-                locations: { $0.progression = progression }
+            location = await publication.locate(link)?.copy(
+                locations: { $0.progression = firstProgression }
             )
         }
+
+        return (location, viewport)
     }
 
     public func firstVisibleElementLocator() async -> Locator? {
@@ -643,7 +687,7 @@ open class EPUBNavigatorViewController: InputObservableViewController,
             return
         }
 
-        currentLocation = await computeCurrentLocation()
+        (currentLocation, viewport) = await computeCurrentLocationAndViewport()
 
         if
             let delegate = delegate,
@@ -660,7 +704,8 @@ open class EPUBNavigatorViewController: InputObservableViewController,
 
         guard
             let paginationView = paginationView,
-            let spreadIndex = spreads.firstIndexWithHREF(locator.href),
+            let index = readingOrder.firstIndexWithHREF(locator.href),
+            let spreadIndex = spreads.firstIndexWithReadingOrderIndex(index),
             on(.jump(locator))
         else {
             return false
@@ -900,7 +945,8 @@ extension EPUBNavigatorViewController: EPUBNavigatorViewModelDelegate {
                 for (_, view) in paginationView.loadedViews {
                     guard
                         let view = view as? EPUBSpreadView,
-                        view.spread.links.firstWithHREF(href) != nil
+                        let index = readingOrder.firstIndexWithHREF(href),
+                        view.spread.contains(index: index)
                     else {
                         continue
                     }
@@ -943,7 +989,10 @@ extension EPUBNavigatorViewController: EPUBSpreadViewDelegate {
             }
             .joined(separator: "\n")
 
-        for link in spreadView.spread.links {
+        let links = spreadView.spread.readingOrderIndices
+            .compactMap { readingOrder.getOrNil($0) }
+
+        for link in links {
             let href = link.url()
             for (group, decorations) in decorations {
                 let decorations = decorations

Sources/Navigator/EPUB/EPUBFixedSpreadView.swift

@@ -38,6 +38,8 @@ final class EPUBNavigatorViewModel: Loggable {
     /// `httpServer`. This is used to serve custom font files, for example.
     @Atomic private var servedFiles: [FileURL: HTTPURL] = [:]
 
+    var readingOrder: ReadingOrder { publication.readingOrder }
+
     convenience init(
         publication: Publication,
         config: EPUBNavigatorViewController.Configuration,

Sources/Navigator/EPUB/EPUBNavigatorViewController.swift

@@ -67,11 +67,11 @@ final class EPUBReflowableSpreadView: EPUBSpreadView {
     }
 
     override func loadSpread() {
-        guard spread.links.count == 1 else {
+        guard spread.readingOrderIndices.count == 1 else {
             log(.error, "Only one document at a time can be displayed in a reflowable spread")
             return
         }
-        let link = spread.leading
+        let link = viewModel.readingOrder[spread.leading]
         let url = viewModel.url(to: link)
         webView.load(URLRequest(url: url.url))
     }
@@ -131,18 +131,21 @@ final class EPUBReflowableSpreadView: EPUBSpreadView {
 
     // MARK: - Location and progression
 
-    override func progression<T>(in href: T) -> Double where T: URLConvertible {
+    override func progression(in index: ReadingOrder.Index) -> Range<Double> {
         guard
-            spread.leading.url().isEquivalentTo(href),
+            spread.leading == index,
             let progression = progression
         else {
-            return 0
+            return 0 ..< 0
         }
         return progression
     }
 
     override func spreadDidLoad() async {
-        if let linkJSON = serializeJSONString(spread.leading.json) {
+        if
+            let link = viewModel.readingOrder.getOrNil(spread.leading),
+            let linkJSON = serializeJSONString(link.json)
+        {
             await evaluateScript("readium.link = \(linkJSON);")
         }
 
@@ -240,9 +243,14 @@ final class EPUBReflowableSpreadView: EPUBSpreadView {
 
     @discardableResult
     private func go(to locator: Locator) async -> Bool {
-        guard ["", "#"].contains(locator.href.string) || spread.contains(href: locator.href) else {
-            log(.warning, "The locator's href is not in the spread")
-            return false
+        if !["", "#"].contains(locator.href.string) {
+            guard
+                let index = viewModel.readingOrder.firstIndexWithHREF(locator.href),
+                spread.contains(index: index)
+            else {
+                log(.warning, "The locator's href is not in the spread")
+                return false
+            }
         }
 
         if locator.text.highlight != nil {
@@ -310,22 +318,29 @@ final class EPUBReflowableSpreadView: EPUBSpreadView {
 
     // MARK: - Progression
 
-    // Current progression in the page.
-    private var progression: Double?
+    // Current progression range in the page.
+    private var progression: Range<Double>?
     // To check if a progression change was cancelled or not.
-    private var previousProgression: Double?
+    private var previousProgression: Range<Double>?
 
     // Called by the javascript code to notify that scrolling ended.
     private func progressionDidChange(_ body: Any) {
-        guard isSpreadLoaded, let bodyString = body as? String, var newProgression = Double(bodyString) else {
+        guard
+            isSpreadLoaded,
+            let body = body as? [String: Any],
+            var firstProgression = body["first"] as? Double,
+            var lastProgression = body["last"] as? Double
+        else {
             return
         }
-        newProgression = min(max(newProgression, 0.0), 1.0)
+        precondition(firstProgression <= lastProgression)
+        firstProgression = min(max(firstProgression, 0.0), 1.0)
+        lastProgression = min(max(lastProgression, 0.0), 1.0)
 
         if previousProgression == nil {
             previousProgression = progression
         }
-        progression = newProgression
+        progression = firstProgression ..< lastProgression
 
         setNeedsNotifyPagesDidChange()
     }