Optimize scrolling to an EPUB locator with a CSS selector (#435)

CHANGELOG.md

@@ -12,7 +12,6 @@ All notable changes to this project will be documented in this file. Take a look
 
 * Support for standalone audio files and their metadata (contributed by [@domkm](https://github.com/readium/swift-toolkit/pull/414)).
 
-
 ### Changed
 
 The Readium Swift toolkit now requires a minimum of iOS 13.
@@ -26,6 +25,12 @@ The Readium Swift toolkit now requires a minimum of iOS 13.
 
 * EPUB: The `scroll` preference is now forced to `true` when rendering vertical text (e.g. CJK vertical). [See this discussion for the rationale](https://github.com/readium/swift-toolkit/discussions/370).
 
+### Fixed
+
+#### Navigator
+
+* Optimized scrolling to an EPUB text-based locator if it contains a CSS selector.
+
 
 ## [3.0.0-alpha.1]
 

Sources/Navigator/EPUB/EPUBReflowableSpreadView.swift

@@ -254,9 +254,9 @@ final class EPUBReflowableSpreadView: EPUBSpreadView {
         case let .locator(locator):
             go(to: locator) { _ in completion() }
         case .start:
-            go(toProgression: 0) { _ in completion() }
+            scroll(toProgression: 0) { _ in completion() }
         case .end:
-            go(toProgression: 1) { _ in completion() }
+            scroll(toProgression: 1) { _ in completion() }
         }
     }
 
@@ -268,18 +268,18 @@ final class EPUBReflowableSpreadView: EPUBSpreadView {
         }
 
         if locator.text.highlight != nil {
-            go(toText: locator.text, completion: completion)
+            scroll(toLocator: locator, completion: completion)
             // FIXME: find the first fragment matching a tag ID (need a regex)
         } else if let id = locator.locations.fragments.first, !id.isEmpty {
-            go(toTagID: id, completion: completion)
+            scroll(toTagID: id, completion: completion)
         } else {
             let progression = locator.locations.progression ?? 0
-            go(toProgression: progression, completion: completion)
+            scroll(toProgression: progression, completion: completion)
         }
     }
 
     /// Scrolls at given progression (from 0.0 to 1.0)
-    private func go(toProgression progression: Double, completion: @escaping (Bool) -> Void) {
+    private func scroll(toProgression progression: Double, completion: @escaping (Bool) -> Void) {
         guard progression >= 0, progression <= 1 else {
             log(.warning, "Scrolling to invalid progression \(progression)")
             completion(false)
@@ -301,7 +301,7 @@ final class EPUBReflowableSpreadView: EPUBSpreadView {
     }
 
     /// Scrolls at the tag with ID `tagID`.
-    private func go(toTagID tagID: String, completion: @escaping (Bool) -> Void) {
+    private func scroll(toTagID tagID: String, completion: @escaping (Bool) -> Void) {
         evaluateScript("readium.scrollToId(\'\(tagID)\');") { result in
             switch result {
             case let .success(value):
@@ -314,12 +314,12 @@ final class EPUBReflowableSpreadView: EPUBSpreadView {
     }
 
     /// Scrolls at the snippet matching the given text context.
-    private func go(toText text: Locator.Text, completion: @escaping (Bool) -> Void) {
-        guard let json = text.jsonString else {
+    private func scroll(toLocator locator: Locator, completion: @escaping (Bool) -> Void) {
+        guard let json = locator.jsonString else {
             completion(false)
             return
         }
-        evaluateScript("readium.scrollToText(\(json));") { result in
+        evaluateScript("readium.scrollToLocator(\(json));") { result in
             switch result {
             case let .success(value):
                 completion((value as? Bool) ?? false)

Sources/Navigator/EPUB/Scripts/src/index.js

@@ -15,7 +15,7 @@ import {
   scrollRight,
   scrollToId,
   scrollToPosition,
-  scrollToText,
+  scrollToLocator,
   setProperty,
   setCSSProperties,
 } from "./utils";
@@ -26,7 +26,7 @@ global.readium = {
   // utils
   scrollToId: scrollToId,
   scrollToPosition: scrollToPosition,
-  scrollToText: scrollToText,
+  scrollToLocator: scrollToLocator,
   scrollLeft: scrollLeft,
   scrollRight: scrollRight,
   setCSSProperties: setCSSProperties,

Sources/Navigator/EPUB/Scripts/src/utils.js

@@ -172,10 +172,10 @@ export function scrollToPosition(position, dir) {
 
 // Scrolls to the first occurrence of the given text snippet.
 //
-// The expected text argument is a Locator Text object, as defined here:
+// The expected text argument is a Locator object, as defined here:
 // https://readium.org/architecture/models/locators/
-export function scrollToText(text) {
-  let range = rangeFromLocator({ text });
+export function scrollToLocator(locator) {
+  let range = rangeFromLocator(locator);
   if (!range) {
     return false;
   }