@internetarchive/bookreader 5.0.0-88-alpha.11 → 5.0.0-89

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

@@ -1,3 +1,4 @@
+// @ts-check
 /** @typedef {import('./BookModel.js').PageNumString} PageNumString */
 /** @typedef {import('./BookModel.js').LeafNum} LeafNum */
 
@@ -140,8 +141,18 @@ export const DEFAULT_OPTIONS = {
    * but going forward we'll keep them here.
    **/
   plugins: {
-    /** @type {import('../plugins/plugin.text_selection.js').TextSelectionPluginOptions} */
+    /** @type {import('../plugins/plugin.archive_analytics.js').ArchiveAnalyticsPlugin['options']}*/
+    archiveAnalytics: null,
+    /** @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,
   },
 
   /**
@@ -183,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

@@ -23,9 +23,8 @@ This file is part of BookReader.
 import 'jquery-ui/ui/widget.js';
 import 'jquery-ui/ui/widgets/mouse.js';
 import 'jquery-ui-touch-punch';
-import jQuery from 'jquery';
 
-// import PACKAGE_JSON from '../package.json';
+import PACKAGE_JSON from '../package.json';
 import * as utils from './BookReader/utils.js';
 import { exposeOverrideable } from './BookReader/utils/classes.js';
 import { Navbar } from './BookReader/Navbar/Navbar.js';
@@ -54,7 +53,7 @@ export default function BookReader(overrides = {}) {
   this.setup(options);
 }
 
-BookReader.version = '123';
+BookReader.version = PACKAGE_JSON.version;
 
 // Mode constants
 /** 1 page view */
@@ -63,6 +62,33 @@ BookReader.constMode1up = 1;
 BookReader.constMode2up = 2;
 /** thumbnails view */
 BookReader.constModeThumb = 3;
+
+// Although this can actualy have any BookReaderPlugin subclass as value, we
+// hardcode the known plugins here for type checking
+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,
+};
+
+/**
+ * @param {string} pluginName
+ * @param {typeof import('./BookReaderPlugin.js').BookReaderPlugin} plugin
+ */
+BookReader.registerPlugin = function(pluginName, plugin) {
+  if (BookReader.PLUGINS[pluginName]) {
+    console.warn(`Plugin ${pluginName} already registered. Overwriting.`);
+  }
+  BookReader.PLUGINS[pluginName] = plugin;
+};
+
 /** image cache */
 BookReader.imageCache = null;
 
@@ -90,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;
 
@@ -148,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
@@ -242,6 +296,7 @@ BookReader.prototype.setup = function(options) {
   this.imageCache = new ImageCache(this.book, {
     useSrcSet: this.options.useSrcSet,
     reduceSet: this.reduceSet,
+    renderPageURI: options.renderPageURI.bind(this),
   });
 
   /**
@@ -350,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) {
@@ -539,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
@@ -586,6 +646,16 @@ BookReader.prototype.init = function() {
     this.enterFullscreen(true);
   }
 
+  // Init plugins
+  for (const [pluginName, plugin] of Object.entries(this._plugins)) {
+    try {
+      plugin.init();
+    }
+    catch (e) {
+      console.error(`Error initializing plugin ${pluginName}`, e);
+    }
+  }
+
   this.init.initComplete = true;
   this.trigger(BookReader.eventNames.PostInit);
 
@@ -776,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) {
@@ -829,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;
 };
 
@@ -1060,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() {
@@ -1132,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,
@@ -1178,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');
@@ -1277,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);
@@ -1288,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);
@@ -1479,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

@@ -0,0 +1,44 @@
+// @ts-check
+/** @typedef {import("./BookReader.js").default} BookReader */
+
+/**
+ * @template TOptions
+ */
+export class BookReaderPlugin {
+  /**
+   * @param {BookReader} br
+   */
+  constructor(br) {
+    /** @type {BookReader} */
+    this.br = br;
+    /** @type {TOptions} */
+    this.options;
+  }
+
+  /**
+   * @abstract
+   * @param {TOptions} options
+   **/
+  setup(options) {
+    this.options = Object.assign({}, this.options, options);
+  }
+
+  /** @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/_BRnav.scss

@@ -110,9 +110,6 @@
         display: block;
       }
     }
-    &.hide {
-      display: none;
-    }
   }
 }
 

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;

package/src/css/_controls.scss

@@ -81,6 +81,10 @@
     height: 30px;
   }
 
+  .controls .hide {
+    display: none;
+  }
+
   @keyframes slideUp {
     from {
       opacity: 0;