@internetarchive/bookreader 5.0.0-10-alpha-3 → 5.0.0-101

package/src/BookReader/options.js

@@ -1,3 +1,4 @@
+// @ts-check
 /** @typedef {import('./BookModel.js').PageNumString} PageNumString */
 /** @typedef {import('./BookModel.js').LeafNum} LeafNum */
 
@@ -25,9 +26,13 @@ export const DEFAULT_OPTIONS = {
   thumbMaxLoading: 4,
   /** spacing between thumbnails */
   thumbPadding: 10,
+  /** min zoom in columns */
+  thumbMinZoomColumns: 2,
+  /** max zoom out columns */
+  thumbMaxZoomColumns: 8,
 
   /** @type {number | 'fast' | 'slow'} speed for flip animation */
-  flipSpeed: 'fast',
+  flipSpeed: 400,
 
   showToolbar: true,
   showNavbar: true,
@@ -61,7 +66,7 @@ export const DEFAULT_OPTIONS = {
     {reduce: 2, autofit: null},
     {reduce: 3, autofit: null},
     {reduce: 4, autofit: null},
-    {reduce: 6, autofit: null}
+    {reduce: 6, autofit: null},
   ],
 
   /** Object to hold parameters related to 1up mode */
@@ -79,7 +84,7 @@ export const DEFAULT_OPTIONS = {
     /** Width of book spine  $$$ consider sizing based on book length */
     bookSpineDivWidth: 64,
     /** @type {AutoFitValues} */
-    autofit: 'auto'
+    autofit: 'auto',
   },
 
   onePageMinBreakpoint: 800,
@@ -92,6 +97,11 @@ export const DEFAULT_OPTIONS = {
   /** @type {string} */
   bookUrlTitle: null,
   enableBookTitleLink: true,
+  /**
+   * @type {string} A globally unique URI for the book. This is used to
+   * save data like annotations the user makes to the book.
+   */
+  bookUri: null,
   /**
    * @type {string} language in ISO 639-1 (PRIVATE: Will also
    * handle language name in English, native name, 639-2/T, or 639-2/B . (archive.org books
@@ -136,8 +146,26 @@ export const DEFAULT_OPTIONS = {
    * but going forward we'll keep them here.
    **/
   plugins: {
-    /** @type {import('../plugins/plugin.text_selection.js').TextSelectionPluginOptions} */
-    textSelection: null,
+    /** @type {Partial<import('../plugins/plugin.archive_analytics.js').ArchiveAnalyticsPlugin['options'>]}*/
+    archiveAnalytics: {},
+    /** @type {Partial<import('../plugins/plugin.autoplay.js').AutoplayPlugin['options'>]}*/
+    autoplay: {},
+    /** @type {Partial<import('../plugins/plugin.chapters.js').ChaptersPlugin['options']>} */
+    chapters: {},
+    /** @type {Partial<import('../plugins/plugin.experiments.js').ExperimentsPlugin['options']>} */
+    experiments: {},
+    /** @type {Partial<import('../plugins/plugin.iiif.js').IiifPlugin['options']>} */
+    iiif: {},
+    /** @type {Partial<import('../plugins/plugin.resume.js').ResumePlugin['options']>} */
+    resume: {},
+    /** @type {Partial<import('../plugins/search/plugin.search.js').SearchPlugin['options']>} */
+    search: {},
+    /** @type {Partial<import('../plugins/plugin.text_selection.js').TextSelectionPlugin['options']>} */
+    textSelection: {},
+    /** @type {Partial<import('../plugins/translate/plugin.translate.js').TranslatePlugin['options']>} */
+    translate: {},
+    /** @type {Partial<import('../plugins/tts/plugin.tts.js').TtsPlugin['options']>} */
+    tts: {},
   },
 
   /**
@@ -176,16 +204,32 @@ export const DEFAULT_OPTIONS = {
    */
   data: [],
 
-  /** Advanced methods for page rendering */
+  /** @type {import('../plugins/plugin.chapters.js').TocEntry[]} */
+  table_of_contents: null,
+
+  /**
+   * 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
@@ -218,31 +262,31 @@ export const DEFAULT_OPTIONS = {
       visible: true,
       label: 'Flip left',
       className: 'book_left',
-      iconClassName: 'left-arrow'
+      iconClassName: 'left-arrow',
     },
     bookRight: {
       visible: true,
       label: 'Flip right',
       className: 'book_right',
-      iconClassName: 'left-arrow hflip'
+      iconClassName: 'left-arrow hflip',
     },
     onePage: {
       visible: true,
       label: 'One-page view',
       className: 'onepg',
-      iconClassName: 'onepg'
+      iconClassName: 'onepg',
     },
     twoPage: {
       visible: true,
       label: 'Two-page view',
       className: 'twopg',
-      iconClassName: 'twopg'
+      iconClassName: 'twopg',
     },
     thumbnail: {
       visible: true,
       label: 'Thumbnail view',
       className: 'thumb',
-      iconClassName: 'thumb'
+      iconClassName: 'thumb',
     },
     viewmode: {
       visible: true,
@@ -253,19 +297,19 @@ export const DEFAULT_OPTIONS = {
       visible: true,
       label: 'Zoom out',
       className: 'zoom_out',
-      iconClassName: 'magnify'
+      iconClassName: 'magnify',
     },
     zoomIn: {
       visible: true,
       label: 'Zoom in',
       className: 'zoom_in',
-      iconClassName: 'magnify plus'
+      iconClassName: 'magnify plus',
     },
     fullScreen: {
       visible: true,
       label: 'Toggle fullscreen',
       className: 'full',
-      iconClassName: 'fullscreen'
+      iconClassName: 'fullscreen',
     },
   },
 
@@ -275,6 +319,12 @@ export const DEFAULT_OPTIONS = {
    */
   startFullscreen: false,
 
+  /**
+   * @type {Boolean}
+   * will show logo at fullscreen mode
+  */
+  enableFSLogoShortcut: false,
+
   /**
    * @type {Boolean}
    * On init, by default, we want to handle resizing bookreader
@@ -288,9 +338,24 @@ export const DEFAULT_OPTIONS = {
    * On init, by default, we want to use srcSet for images
    */
   useSrcSet: false,
+
+  /**
+   * @type {string}
+   * Path to the image to display when a page is unviewable (i.e. when
+   * displaying a preview of a book).
+   *
+   * Relative to the imagesBaseURL if a relative path is specified.
+   */
+  unviewablePageURI: './unviewable_page.png',
 };
 
-/** @typedef {'width' | 'height' | 'auto' | 'none'} AutoFitValues */
+/**
+ * @typedef {'width' | 'height' | 'auto' | 'none'} AutoFitValues
+ * - width: fill the width of the container
+ * - height: fill the height of the container
+ * - auto: fill the width or height of the container, whichever is smaller
+ * - none: do not autofit
+ **/
 
 /**
  * @typedef {object} ReductionFactor
@@ -318,3 +383,9 @@ export const DEFAULT_OPTIONS = {
 
 /** @typedef {typeof DEFAULT_OPTIONS} BookReaderOptions */
 
+/**
+ * Thrown when an error occurs while parsing options.
+ * Potentially recoverable and non-halting.
+ */
+export class OptionsParseError extends Error {
+}

package/src/BookReader/utils/HTMLDimensionsCacher.js

@@ -0,0 +1,44 @@
+// @ts-check
+import { debounce } from '../utils.js';
+
+/**
+ * Computing these things repeatedly is expensive (the browser needs to
+ * do a lot of computations/redrawing to make sure these are correct),
+ * so we store them here, and only recompute them when necessary:
+ * - window resize could have cause the container to change size
+ * - zoom could have cause scrollbars to appear/disappear, changing
+ *   the client size.
+ */
+export class HTMLDimensionsCacher {
+  clientWidth = 100;
+  clientHeight = 100;
+
+  boundingClientRect = { top: 0, left: 0 };
+
+  /**
+   * @param {HTMLElement} element
+   */
+  constructor(element) {
+    /** @type {HTMLElement} */
+    this.element = element;
+  }
+
+  updateClientSizes = () => {
+    const bc = this.element.getBoundingClientRect();
+    this.clientWidth = this.element.clientWidth;
+    this.clientHeight = this.element.clientHeight;
+    this.boundingClientRect.top = bc.top;
+    this.boundingClientRect.left = bc.left;
+  }
+  debouncedUpdateClientSizes = debounce(this.updateClientSizes, 150, false);
+
+  /** @param {EventTarget} win */
+  attachResizeListener(win = window) {
+    win.addEventListener('resize', this.debouncedUpdateClientSizes);
+  }
+
+  /** @param {EventTarget} win */
+  detachResizeListener(win = window) {
+    win.removeEventListener('resize', this.debouncedUpdateClientSizes);
+  }
+}

package/src/BookReader/utils/ScrollClassAdder.js

@@ -0,0 +1,31 @@
+/** Adds a class while the given element is experiencing scrolling */
+export class ScrollClassAdder {
+  /**
+   * @param {HTMLElement} element
+   * @param {string} className
+   */
+  constructor(element, className) {
+    /** @type {HTMLElement} */
+    this.element = element;
+    /** @type {string} */
+    this.className = className;
+    this.timeout = null;
+  }
+
+  attach() {
+    this.element.addEventListener('scroll', this.onScroll);
+  }
+
+  detach() {
+    this.element.removeEventListener('scroll', this.onScroll);
+  }
+
+  onScroll = () => {
+    this.element.classList.add(this.className);
+    clearTimeout(this.timeout);
+    // TODO: Also remove class on mousemove, touch, click, etc.
+    this.timeout = setTimeout(() => {
+      this.element.classList.remove(this.className);
+    }, 600);
+  }
+}

package/src/BookReader/utils/SelectionObserver.js

@@ -0,0 +1,45 @@
+// @ts-check
+export class SelectionObserver {
+  selecting = false;
+  startedInSelector = false;
+  /** @type {HTMLElement} */
+  target = null;
+
+  /**
+   * @param {string} selector
+   * @param {function('started' | 'cleared', HTMLElement): any} handler
+   */
+  constructor(selector, handler) {
+    this.selector = selector;
+    this.handler = handler;
+  }
+
+  attach() {
+    // We can't just use selectstart, because safari on iOS just
+    // randomly decides when to fire it 😤
+    // document.addEventListener("selectstart", this._onSelectStart);
+    // This has to be on document :/
+    document.addEventListener("selectionchange", this._onSelectionChange);
+  }
+
+  detach() {
+    document.removeEventListener("selectionchange", this._onSelectionChange);
+  }
+
+  _onSelectionChange = () => {
+    const sel = window.getSelection();
+
+    if (!this.selecting && sel.toString()) {
+      const target = $(sel.anchorNode).closest(this.selector)[0];
+      if (!target) return;
+      this.target = target;
+      this.selecting = true;
+      this.handler('started', this.target);
+    }
+
+    if (this.selecting && (sel.isCollapsed || !sel.toString() || !$(sel.anchorNode).closest(this.selector)[0])) {
+      this.selecting = false;
+      this.handler('cleared', this.target);
+    }
+  };
+}

package/src/BookReader/utils/classes.js

@@ -31,6 +31,6 @@ export function exposeOverrideable(FromClass, fromMethod, fromTransform, ToClass
         return overrideFn.apply(newThis, arguments);
       };
       wrapper = overrideFn;
-    }
+    },
   });
 }

package/src/BookReader/utils.js

@@ -40,6 +40,24 @@ export function notInArray(value, array) {
   return !array.includes(value);
 }
 
+/**
+ * Determines the active element, going into shadow doms.
+ * @return {Element}
+ */
+export function getActiveElement(doc = document, recurseShadowDom = true) {
+  const activeElement = doc.activeElement;
+  if (recurseShadowDom && activeElement?.shadowRoot) {
+    return getActiveElement(activeElement.shadowRoot, true);
+  }
+  return activeElement;
+}
+
+/** Check if an input field/textarea is active. Also checks shadow DOMs. */
+export function isInputActive(doc = document) {
+  const activeEl = getActiveElement(doc);
+  return activeEl?.tagName == "INPUT" || activeEl?.tagName == "TEXTAREA";
+}
+
 /**
  * @param {HTMLIFrameElement} iframe
  * @return {Document}
@@ -80,16 +98,17 @@ export function encodeURIComponentPlus(value) {
 }
 
 /**
+ * @template {Function} T
  * Returns a function, that, as long as it continues to be invoked, will not
  * be triggered. The function will be called after it stops being called for
  * N milliseconds. If `immediate` is passed, trigger the function on the
  * leading edge, instead of the trailing.
  * @see https://davidwalsh.name/javascript-debounce-function
  *
- * @param {Function} func
+ * @param {T} func
  * @param {number} wait
  * @param {boolean} immediate
- * @return {Function}
+ * @return {T}
  */
 export function debounce(func, wait, immediate) {
   let timeout;
@@ -108,12 +127,13 @@ export function debounce(func, wait, immediate) {
 }
 
 /**
+ * @template T
  * Throttle function
  * @see https://remysharp.com/2010/07/21/throttling-function-calls
- * @param {Function} fn
+ * @param {T} fn
  * @param {number} threshold
  * @param {boolean} delay
- * @return {Function}
+ * @return {T}
  */
 export function throttle(fn, threshold, delay) {
   threshold || (threshold = 250);
@@ -160,14 +180,6 @@ export function PolyfilledCustomEvent(eventName, {bubbles = false, cancelable =
   return event;
 }
 
-/**
- * Promise based sleep - resolves at default 500ms
- * @param {Number} wait time in milliseconds
- */
-export function sleep(ms = 500) {
-  return new Promise(res => setTimeout(res(true), ms));
-}
-
 /*
  * Returns the number pixels something should be rendered at to be ~1n on the users
  * screen when measured with a ruler.
@@ -187,3 +199,115 @@ export function calcScreenDPI() {
   // This will return 0 in testing; never want it to be 0!
   return screenDPI == 0 ? 100 : screenDPI;
 }
+
+/**
+ * @param {number[]} nums
+ * @returns {number}
+ */
+export function sum(nums) {
+  return nums.reduce((cur, acc) => cur + acc, 0);
+}
+
+/**
+ * @template T
+ * @param {Generator<T>} gen
+ * @returns {T[]}
+ */
+export function genToArray(gen) {
+  const result = [];
+  for (const item of gen) {
+    result.push(item);
+  }
+  return result;
+}
+
+/**
+ * Check if arrays contain the same elements. Does reference comparison.
+ * @param {Array} arr1
+ * @param {Array} arr2
+ */
+export function arrEquals(arr1, arr2) {
+  return arr1.length == arr2.length && arr1.every((x, i) => x == arr2[i]);
+}
+
+/**
+ * Check if array has changed; namely to be used with lit's property.hasChanged
+ * @param {Array} [arr1]
+ * @param {Array} [arr2]
+ */
+export function arrChanged(arr1, arr2) {
+  return arr1 && arr2 && !arrEquals(arr1, arr2);
+}
+
+/**
+ * Waits the provided number of ms and then resolves with a promise
+ * @param {number} ms
+ **/
+export async function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * @template T
+ * @param {function(): T} fn
+ * @param {Object} options
+ * @param {function(T): boolean} [options.until]
+ * @return {T | undefined}
+ */
+export async function poll(fn, { step = 50, timeout = 500, until = val => Boolean(val), _sleep = sleep } = {}) {
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    const result = fn();
+    if (until(result)) return result;
+    await _sleep(step);
+  }
+}
+
+/**
+ * Convert a EventTarget style event into a promise
+ * @param {EventTarget} target
+ * @param {string} eventType
+ * @return {Promise<Event>}
+ */
+export function promisifyEvent(target, eventType) {
+  return new Promise(res => {
+    const resolver = ev => {
+      target.removeEventListener(eventType, resolver);
+      res(ev);
+    };
+    target.addEventListener(eventType, resolver);
+  });
+}
+
+/**
+ * Escapes regex special characters in a string. Allows for safe usage in regexes.
+ * Src: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions
+ * @param {string} string
+ * @returns {string}
+ */
+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);
+}
+
+/**
+ * @template T
+ * @param {T[]} array
+ * @param {function(T): number} [valueFn]
+ */
+export function sortBy(array, valueFn) {
+  return array.sort((a, b) => {
+    const aValue = valueFn ? valueFn(a) : a;
+    const bValue = valueFn ? valueFn(b) : b;
+    return aValue < bValue ? -1 : aValue > bValue ? 1 : 0;
+  });
+}