@internetarchive/bookreader 5.0.0-88 → 5.0.0-89

package/src/BookReader/ImageCache.js

@@ -7,8 +7,10 @@
 /** @typedef {import("./BookModel").BookModel} BookModel */
 /** @typedef {import("./BookModel").PageIndex} PageIndex */
 /** @typedef {import("./ReduceSet").ReduceSet} ReduceSet */
+/** @typedef {import("./options").BookReaderOptions} BookReaderOptions */
 
 import { Pow2ReduceSet } from "./ReduceSet";
+import { DEFAULT_OPTIONS } from "./options";
 
 export class ImageCache {
   /**
@@ -16,11 +18,25 @@ export class ImageCache {
    * @param {object} opts
    * @param {boolean} [opts.useSrcSet]
    * @param {ReduceSet} [opts.reduceSet]
+   * @param {BookReaderOptions['renderPageURI']} [opts.renderPageURI]
    */
-  constructor(book, { useSrcSet = false, reduceSet = Pow2ReduceSet } = {}) {
+  constructor(
+    book,
+    {
+      useSrcSet = false,
+      reduceSet = Pow2ReduceSet,
+      renderPageURI = DEFAULT_OPTIONS.renderPageURI,
+    } = {},
+  ) {
+    /** @type {BookModel} */
     this.book = book;
+    /** @type {boolean} */
     this.useSrcSet = useSrcSet;
+    /** @type {ReduceSet} */
     this.reduceSet = reduceSet;
+    /** @type {BookReaderOptions['renderPageURI']} */
+    this.renderPageURI = renderPageURI;
+
     /** @type {{ [index: number]: { reduce: number, loaded: boolean }[] }} */
     this.cache = {};
     this.defaultScale = 8;
@@ -33,19 +49,35 @@ export class ImageCache {
    *
    * @param {PageIndex} index
    * @param {Number} reduce
+   * @param {HTMLImageElement?} [img]
    */
-  image(index, reduce) {
+  image(index, reduce, img = null) {
+    const finalReduce = this.getFinalReduce(index, reduce);
+    return this._serveImageElement(index, finalReduce, img);
+  }
+
+  /**
+   * Get the final reduce factor to use for the given index
+   *
+   * @param {PageIndex} index
+   * @param {Number} reduce
+   */
+  getFinalReduce(index, reduce) {
     const cachedImages = this.cache[index] || [];
     const sufficientImages = cachedImages
       .filter(x => x.loaded && x.reduce <= reduce);
+
     if (sufficientImages.length) {
       // Choose the largest reduction factor that meets our needs
       const bestReduce = Math.max(...sufficientImages.map(e => e.reduce));
-      return this._serveImageElement(index, bestReduce);
+      // Don't need to floor here, since we know the image is in the cache
+      // and hence was already floor'd by the below `else` clause before
+      // it was added
+      return bestReduce;
     } else {
       // Don't use a cache entry; i.e. a fresh fetch will be made
       // for this reduce
-      return this._serveImageElement(index, reduce);
+      return this.reduceSet.floor(reduce);
     }
   }
 
@@ -87,26 +119,27 @@ export class ImageCache {
    *
    * @param {PageIndex} index
    * @param {number} reduce
+   * @param {HTMLImageElement?} [img]
    * @returns {JQuery<HTMLImageElement>} with base image classes
    */
-  _serveImageElement(index, reduce) {
-    const validReduce = this.reduceSet.floor(reduce);
-    let cacheEntry = this.cache[index]?.find(e => e.reduce == validReduce);
+  _serveImageElement(index, reduce, img = null) {
+    let cacheEntry = this.cache[index]?.find(e => e.reduce == reduce);
     if (!cacheEntry) {
-      cacheEntry = { reduce: validReduce, loaded: false };
+      cacheEntry = { reduce, loaded: false };
       const entries = this.cache[index] || (this.cache[index] = []);
       entries.push(cacheEntry);
     }
     const page = this.book.getPage(index);
 
-    const $img = $('<img />', {
-      'class': 'BRpageimage',
-      'alt': 'Book page image',
-      src: page.getURI(validReduce, 0),
-    })
-      .data('reduce', validReduce);
+    const uri = page.getURI(reduce, 0);
+    const $img = $(img || document.createElement('img'))
+      .addClass('BRpageimage')
+      .attr('alt', 'Book page image')
+      .data('reduce', reduce)
+      .data('src', uri);
+    this.renderPageURI($img[0], uri);
     if (this.useSrcSet) {
-      $img.attr('srcset', page.getURISrcSet(validReduce));
+      $img.attr('srcset', page.getURISrcSet(reduce));
     }
     if (!cacheEntry.loaded) {
       $img.one('load', () => cacheEntry.loaded = true);

package/src/BookReader/Mode2UpLit.js

@@ -493,13 +493,14 @@ export class Mode2UpLit extends LitElement {
   /**
    * @param {'left' | 'right' | 'next' | 'prev' | PageIndex | PageModel | {left: PageModel | null, right: PageModel | null}} nextSpread
    */
-  async flipAnimation(nextSpread, { animate = true } = {}) {
+  async flipAnimation(nextSpread, { animate = true, flipSpeed = this.flipSpeed } = {}) {
     const curSpread = (this.pageLeft || this.pageRight)?.spread;
     if (!curSpread) {
       // Nothings been actually rendered yet! Will be corrected during initFirstRender
       return;
     }
 
+    flipSpeed = flipSpeed || this.flipSpeed; // Handle null
     nextSpread = this.parseNextSpread(nextSpread);
     if (this.activeFlip || !nextSpread) return;
 
@@ -559,7 +560,7 @@ export class Mode2UpLit extends LitElement {
 
       /** @type {KeyframeAnimationOptions} */
       const animationStyle = {
-        duration: this.flipSpeed + this.activeFlip.pagesFlippingCount,
+        duration: flipSpeed + this.activeFlip.pagesFlippingCount,
         easing: 'ease-in',
         fill: 'none',
       };

package/src/BookReader/PageContainer.js

@@ -2,6 +2,8 @@
 /** @typedef {import('./BookModel.js').PageModel} PageModel */
 /** @typedef {import('./ImageCache.js').ImageCache} ImageCache */
 
+import { sleep } from './utils.js';
+
 
 export class PageContainer {
   /**
@@ -9,12 +11,10 @@ export class PageContainer {
    * @param {object} opts
    * @param {boolean} opts.isProtected Whether we're in a protected book
    * @param {ImageCache} opts.imageCache
-   * @param {string} opts.loadingImage
    */
-  constructor(page, {isProtected, imageCache, loadingImage}) {
+  constructor(page, {isProtected, imageCache}) {
     this.page = page;
     this.imageCache = imageCache;
-    this.loadingImage = loadingImage;
     this.$container = $('<div />', {
       'class': `BRpagecontainer ${page ? `pagediv${page.index}` : 'BRemptypage'}`,
       css: { position: 'absolute' },
@@ -43,39 +43,58 @@ export class PageContainer {
       return;
     }
 
-    const alreadyLoaded = this.imageCache.imageLoaded(this.page.index, reduce);
-    const nextBestLoadedReduce = !alreadyLoaded && this.imageCache.getBestLoadedReduce(this.page.index, reduce);
+    const finalReduce = this.imageCache.getFinalReduce(this.page.index, reduce);
+    const newImageURI = this.page.getURI(finalReduce, 0);
 
-    // Create high res image
-    const $newImg = this.imageCache.image(this.page.index, reduce);
+    // Note: These must be computed _before_ we call .image()
+    const alreadyLoaded = this.imageCache.imageLoaded(this.page.index, finalReduce);
+    const nextBestLoadedReduce = this.imageCache.getBestLoadedReduce(this.page.index, reduce);
 
     // Avoid removing/re-adding the image if it's already there
     // This can be called quite a bit, so we need to be fast
-    if (this.$img?.[0].src == $newImg[0].src) {
+    if (this.$img?.data('src') == newImageURI) {
       return this;
     }
 
-    this.$img?.remove();
-    this.$img = $newImg.prependTo(this.$container);
+    let $oldImg = this.$img;
+    this.$img = this.imageCache.image(this.page.index, finalReduce);
+    if ($oldImg) {
+      this.$img.insertAfter($oldImg);
+    } else {
+      this.$img.prependTo(this.$container);
+    }
 
-    const backgroundLayers = [];
     if (!alreadyLoaded) {
       this.$container.addClass('BRpageloading');
-      backgroundLayers.push(`url("${this.loadingImage}") center/20px no-repeat`);
-    }
-    if (nextBestLoadedReduce) {
-      backgroundLayers.push(`url("${this.page.getURI(nextBestLoadedReduce, 0)}") center/100% 100% no-repeat`);
     }
 
-    if (!alreadyLoaded) {
-      this.$img
-        .css('background', backgroundLayers.join(','))
-        .one('loadend', async (ev) => {
-          $(ev.target).css({ 'background': '' });
-          $(ev.target).parent().removeClass('BRpageloading');
-        });
+    if (!alreadyLoaded && nextBestLoadedReduce) {
+      // If we have a slightly lower quality image loaded, use that as the background
+      // while the higher res one loads
+      const nextBestUri = this.page.getURI(nextBestLoadedReduce, 0);
+      if ($oldImg) {
+        if ($oldImg.data('src') == nextBestUri) {
+          // Do nothing! It's already showing the right thing
+        } else {
+          // We have a different src, need to update the src
+          this.imageCache.image(this.page.index, nextBestLoadedReduce, $oldImg[0]);
+        }
+      } else {
+        // We don't have an old <img>, so we need to create a new one
+        $oldImg = this.imageCache.image(this.page.index, nextBestLoadedReduce);
+        $oldImg.prependTo(this.$container);
+      }
     }
 
+    this.$img
+      .one('load', async (ev) => {
+        this.$container.removeClass('BRpageloading');
+        // `load` can fire a little early, so wait a spell before removing the old image
+        // to avoid flicker
+        await sleep(100);
+        $oldImg?.remove();
+      });
+
     return this;
   }
 }

package/src/BookReader/options.js

@@ -143,8 +143,16 @@ export const DEFAULT_OPTIONS = {
   plugins: {
     /** @type {import('../plugins/plugin.archive_analytics.js').ArchiveAnalyticsPlugin['options']}*/
     archiveAnalytics: null,
-    /** @type {import('../plugins/plugin.text_selection.js').TextSelectionPluginOptions} */
+    /** @type {import('../plugins/plugin.autoplay.js').AutoplayPlugin['options']}*/
+    autoplay: null,
+    /** @type {import('../plugins/plugin.iiif.js').IiifPlugin['options']} */
+    iiif: null,
+    /** @type {import('../plugins/plugin.resume.js').ResumePlugin['options']} */
+    resume: null,
+    /** @type {import('../plugins/plugin.text_selection.js').TextSelectionPlugin['options']} */
     textSelection: null,
+    /** @type {import('../plugins/tts/plugin.tts.js').TtsPlugin['options']} */
+    tts: null,
   },
 
   /**
@@ -186,16 +194,29 @@ export const DEFAULT_OPTIONS = {
   /** @type {import('../plugins/plugin.chapters.js').TocEntry[]} */
   table_of_contents: null,
 
-  /** Advanced methods for page rendering */
+  /**
+   * Advanced methods for page rendering.
+   * All option functions have their `this` object set to the BookReader instance.
+   **/
+
   /** @type {() => number} */
   getNumLeafs: null,
   /** @type {(index: number) => number} */
   getPageWidth: null,
   /** @type {(index: number) => number} */
   getPageHeight: null,
-  /** @type {(index: number, reduce: number, rotate: number) => *} */
+  /** @type {(index: number, reduce: number, rotate: number) => string} */
   getPageURI: null,
 
+  /**
+   * @type {(img: HTMLImageElement, uri: string) => Promise<void>}
+   * Render the page URI into the image element. Perform any necessary preloading,
+   * authentication, etc.
+   */
+  renderPageURI(img, uri) {
+    img.src = uri;
+  },
+
   /**
    * @type {(index: number) => 'L' | 'R'}
    * Return which side, left or right, that a given page should be displayed on

package/src/BookReader/utils.js

@@ -288,3 +288,13 @@ export function promisifyEvent(target, eventType) {
 export function escapeRegExp(string) {
   return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
 }
+
+/**
+ * @param {number | 'fast' | 'slow' | string} speed
+ * Parsing of the jquery animation speed; see https://api.jquery.com/animate/
+ */
+export function parseAnimationSpeed(speed) {
+  if (speed === 'slow') return 600;
+  if (speed === 'fast') return 200;
+  return parseInt(speed, 10);
+}

package/src/BookReader.js

@@ -68,6 +68,14 @@ BookReader.constModeThumb = 3;
 BookReader.PLUGINS = {
   /** @type {typeof import('./plugins/plugin.archive_analytics.js').ArchiveAnalyticsPlugin | null}*/
   archiveAnalytics: null,
+  /** @type {typeof import('./plugins/plugin.autoplay.js').AutoplayPlugin | null}*/
+  autoplay: null,
+  /** @type {typeof import('./plugins/plugin.resume.js').ResumePlugin | null}*/
+  resume: null,
+  /** @type {typeof import('./plugins/plugin.text_selection.js').TextSelectionPlugin | null}*/
+  textSelection: null,
+  /** @type {typeof import('./plugins/tts/plugin.tts.js').TtsPlugin | null}*/
+  tts: null,
 };
 
 /**
@@ -108,6 +116,38 @@ BookReader.prototype.setup = function(options) {
   // Store the options used to setup bookreader
   this.options = options;
 
+  // Construct the usual plugins first to get type hints
+  this._plugins = {
+    archiveAnalytics: BookReader.PLUGINS.archiveAnalytics ? new BookReader.PLUGINS.archiveAnalytics(this) : null,
+    autoplay: BookReader.PLUGINS.autoplay ? new BookReader.PLUGINS.autoplay(this) : null,
+    resume: BookReader.PLUGINS.resume ? new BookReader.PLUGINS.resume(this) : null,
+    textSelection: BookReader.PLUGINS.textSelection ? new BookReader.PLUGINS.textSelection(this) : null,
+    tts: BookReader.PLUGINS.tts ? new BookReader.PLUGINS.tts(this) : null,
+  };
+
+  // Delete anything that's null
+  for (const [pluginName, plugin] of Object.entries(this._plugins)) {
+    if (!plugin) delete this._plugins[pluginName];
+  }
+
+  // Now construct the rest of the plugins
+  for (const [pluginName, PluginClass] of Object.entries(BookReader.PLUGINS)) {
+    if (this._plugins[pluginName] || !PluginClass) continue;
+    this._plugins[pluginName] = new PluginClass(this);
+  }
+
+  // And call setup on them
+  for (const [pluginName, plugin] of Object.entries(this._plugins)) {
+    try {
+      plugin.setup(this.options.plugins?.[pluginName] ?? {});
+      // Write the options back; this way the plugin is the source of truth,
+      // and BR just contains a reference to it.
+      this.options.plugins[pluginName] = plugin.options;
+    } catch (e) {
+      console.error(`Error setting up plugin ${pluginName}`, e);
+    }
+  }
+
   /** @type {number} @deprecated some past iterations set this */
   this.numLeafs = undefined;
 
@@ -166,11 +206,7 @@ BookReader.prototype.setup = function(options) {
   this.displayedIndices = [];
 
   this.animating = false;
-  this.flipSpeed = typeof options.flipSpeed === 'number' ? options.flipSpeed : {
-    'fast': 200,
-    'slow': 600,
-  }[options.flipSpeed] || 400;
-  this.flipDelay = options.flipDelay;
+  this.flipSpeed = utils.parseAnimationSpeed(options.flipSpeed) || 400;
 
   /**
      * Represents the first displayed index
@@ -256,30 +292,11 @@ BookReader.prototype.setup = function(options) {
     '_modes.modeThumb': this._modes.modeThumb,
   };
 
-  // Construct the usual suspects first to get type hints
-  this._plugins = {
-    archiveAnalytics: BookReader.PLUGINS.archiveAnalytics ? new BookReader.PLUGINS.archiveAnalytics(this) : null,
-  };
-
-  // Now construct the rest of the plugins
-  for (const [pluginName, PluginClass] of Object.entries(BookReader.PLUGINS)) {
-    if (this._plugins[pluginName] || !PluginClass) continue;
-    this._plugins[pluginName] = new PluginClass(this);
-  }
-
-  // And call setup on them
-  for (const [pluginName, plugin] of Object.entries(this._plugins)) {
-    try {
-      plugin.setup(this.options.plugins?.[pluginName] ?? {});
-    } catch (e) {
-      console.error(`Error setting up plugin ${pluginName}`, e);
-    }
-  }
-
   /** Image cache for general image fetching */
   this.imageCache = new ImageCache(this.book, {
     useSrcSet: this.options.useSrcSet,
     reduceSet: this.reduceSet,
+    renderPageURI: options.renderPageURI.bind(this),
   });
 
   /**
@@ -388,9 +405,9 @@ BookReader.prototype.initParams = function() {
   }
 
   // Check for Resume plugin
-  if (this.options.enablePageResume) {
+  if (this._plugins.resume?.options.enabled) {
     // Check cookies
-    const val = this.getResumeValue();
+    const val = this._plugins.resume.getResumeValue();
     if (val !== null) {
       // If page index different from default
       if (params.index !== val) {
@@ -577,7 +594,12 @@ BookReader.prototype.init = function() {
     this.initToolbar(this.mode, this.ui); // Build inside of toolbar div
   }
   if (this.options.showNavbar) { // default navigation
-    this.initNavbar();
+    const $navBar = this.initNavbar();
+
+    // extend navbar with plugins
+    for (const plugin of Object.values(this._plugins)) {
+      plugin.extendNavBar($navBar);
+    }
   }
 
   // Switch navbar controls on mobile/desktop
@@ -824,11 +846,17 @@ BookReader.prototype.drawLeafs = function() {
  * @param {PageIndex} index
  */
 BookReader.prototype._createPageContainer = function(index) {
-  return new PageContainer(this.book.getPage(index, false), {
+  const pageContainer = new PageContainer(this.book.getPage(index, false), {
     isProtected: this.protected,
     imageCache: this.imageCache,
-    loadingImage: this.imagesBaseURL + 'loading.gif',
   });
+
+  // Call plugin handlers
+  for (const plugin of Object.values(this._plugins)) {
+    plugin._configurePageContainer(pageContainer);
+  }
+
+  return pageContainer;
 };
 
 BookReader.prototype.bindGestures = function(jElement) {
@@ -877,7 +905,7 @@ BookReader.prototype.zoom = function(direction) {
   } else {
     this.activeMode.zoom('out');
   }
-  this.textSelectionPlugin?.stopPageFlip(this.refs.$brContainer);
+  this._plugins.textSelection?.stopPageFlip(this.refs.$brContainer);
   return;
 };
 
@@ -1108,7 +1136,7 @@ BookReader.prototype.switchMode = function(
   const eventName = mode + 'PageViewSelected';
   this.trigger(BookReader.eventNames[eventName]);
 
-  this.textSelectionPlugin?.stopPageFlip(this.refs.$brContainer);
+  this._plugins.textSelection?.stopPageFlip(this.refs.$brContainer);
 };
 
 BookReader.prototype.updateBrClasses = function() {
@@ -1180,7 +1208,7 @@ BookReader.prototype.enterFullscreen = async function(bindKeyboardControls = tru
   }
   this.jumpToIndex(currentIndex);
 
-  this.textSelectionPlugin?.stopPageFlip(this.refs.$brContainer);
+  this._plugins.textSelection?.stopPageFlip(this.refs.$brContainer);
   // Add "?view=theater"
   this.trigger(BookReader.eventNames.fragmentChange);
   // trigger event here, so that animations,
@@ -1226,7 +1254,7 @@ BookReader.prototype.exitFullScreen = async function () {
     await this.activeMode.mode1UpLit.updateComplete;
   }
 
-  this.textSelectionPlugin?.stopPageFlip(this.refs.$brContainer);
+  this._plugins.textSelection?.stopPageFlip(this.refs.$brContainer);
   // Remove "?view=theater"
   this.trigger(BookReader.eventNames.fragmentChange);
   this.refs.$br.removeClass('BRfullscreenAnimation');
@@ -1325,10 +1353,19 @@ BookReader.prototype.leftmost = function() {
   }
 };
 
-BookReader.prototype.next = function({triggerStop = true} = {}) {
+/**
+ * @param {object} options
+ * @param {boolean} [options.triggerStop = true]
+ * @param {number | 'fast' | 'slow'} [options.flipSpeed]
+ */
+BookReader.prototype.next = function({
+  triggerStop = true,
+  flipSpeed = null,
+} = {}) {
   if (this.constMode2up == this.mode) {
     if (triggerStop) this.trigger(BookReader.eventNames.stop);
-    this._modes.mode2Up.mode2UpLit.flipAnimation('next');
+    flipSpeed = utils.parseAnimationSpeed(flipSpeed) || this.flipSpeed;
+    this._modes.mode2Up.mode2UpLit.flipAnimation('next', {flipSpeed});
   } else {
     if (this.firstIndex < this.book.getNumLeafs() - 1) {
       this.jumpToIndex(this.firstIndex + 1);
@@ -1336,13 +1373,22 @@ BookReader.prototype.next = function({triggerStop = true} = {}) {
   }
 };
 
-BookReader.prototype.prev = function({triggerStop = true} = {}) {
+/**
+ * @param {object} options
+ * @param {boolean} [options.triggerStop = true]
+ * @param {number | 'fast' | 'slow'} [options.flipSpeed]
+ */
+BookReader.prototype.prev = function({
+  triggerStop = true,
+  flipSpeed = null,
+} = {}) {
   const isOnFrontPage = this.firstIndex < 1;
   if (isOnFrontPage) return;
 
   if (this.constMode2up == this.mode) {
     if (triggerStop) this.trigger(BookReader.eventNames.stop);
-    this._modes.mode2Up.mode2UpLit.flipAnimation('prev');
+    flipSpeed = utils.parseAnimationSpeed(flipSpeed) || this.flipSpeed;
+    this._modes.mode2Up.mode2UpLit.flipAnimation('prev', {flipSpeed});
   } else {
     if (this.firstIndex >= 1) {
       this.jumpToIndex(this.firstIndex - 1);
@@ -1527,6 +1573,11 @@ BookReader.prototype.bindNavigationHandlers = function() {
         self.$('.BRnavCntl').animate({opacity:.75},250);
       }
     });
+
+  // Call _bindNavigationHandlers on the plugins
+  for (const plugin of Object.values(this._plugins)) {
+    plugin._bindNavigationHandlers();
+  }
 };
 
 /**************************/

package/src/BookReaderPlugin.js

@@ -25,4 +25,20 @@ export class BookReaderPlugin {
 
   /** @abstract */
   init() {}
+
+  /**
+   * @abstract
+   * @protected
+   * @param {import ("./BookReader/PageContainer.js").PageContainer} pageContainer
+   */
+  _configurePageContainer(pageContainer) {
+  }
+
+  /** @abstract @protected */
+  _bindNavigationHandlers() {}
+
+  /**
+   * @param {JQuery<HTMLElement>} $navBar
+   */
+  extendNavBar($navBar) {}
 }

package/src/css/_BRpages.scss

@@ -60,9 +60,28 @@
     left: 0;
     z-index: 1;
   }
-  &.BRpageloading img {
+  &.BRpageloading {
     // Don't show the alt text while loading
-    color: transparent;
+    img {
+      color: transparent;
+    }
+
+    // src can be set async, so hide the image if it's not set
+    img:not([src]) {
+      display: none;
+    }
+
+    &::after {
+      display: block;
+      content: "";
+      width: 20px;
+      height: 20px;
+      position: absolute;
+      left: 50%;
+      top: 50%;
+      transform: translate(-50%, -50%);
+      background: url("images/loading.gif") center/20px no-repeat;
+    }
   }
   &.BRemptypage {
     background: transparent;