@internetarchive/bookreader 5.0.0-18

package/src/BookReader/options.js

@@ -0,0 +1,320 @@
+/** @typedef {import('./BookModel.js').PageNumString} PageNumString */
+/** @typedef {import('./BookModel.js').LeafNum} LeafNum */
+
+export const DEFAULT_OPTIONS = {
+  /**
+   * @type {string} A string, such as "mode/1up". See
+   * http://openlibrary.org/dev/docs/bookurls for valid syntax
+   */
+  defaults: null,
+
+  /** Padding in 1up */
+  padding: 10,
+
+  /** @type {'full' | 'embed' | 'responsive'} UI mode */
+  ui: 'full',
+
+  /** Controls whether nav/toolbar will autohide */
+  uiAutoHide: false,
+
+  /** thumbnail mode */
+  /** number of rows to pre-cache out a view */
+  thumbRowBuffer: 1,
+  thumbColumns: 6,
+  /** number of thumbnails to load at once */
+  thumbMaxLoading: 4,
+  /** spacing between thumbnails */
+  thumbPadding: 10,
+
+  /** @type {number | 'fast' | 'slow'} speed for flip animation */
+  flipSpeed: 'fast',
+
+  showToolbar: true,
+  showNavbar: true,
+  navBarTitle: '',
+
+  showLogo: true,
+  /** Where the logo links to */
+  logoURL: 'https://archive.org',
+
+  /**
+   * Base URL for UI images - should be overridden (before init) by
+   * custom implementations.
+   * $$$ This is the same directory as the images referenced by relative
+   *     path in the CSS.  Would be better to automagically find that path.
+   */
+  imagesBaseURL: '/BookReader/images/',
+
+  /** @type {'pow2' | 'integer'} What reduces are valid for getURI. */
+  reduceSet: 'pow2',
+
+  /**
+   * Zoom levels
+   * @type {ReductionFactor[]}
+   * $$$ provide finer grained zooming, {reduce: 8, autofit: null}, {reduce: 16, autofit: null}
+   * The autofit code ensures that fit to width and fit to height will be available
+   */
+  reductionFactors: [
+    {reduce: 0.25, autofit: null},
+    {reduce: 0.5, autofit: null},
+    {reduce: 1, autofit: null},
+    {reduce: 2, autofit: null},
+    {reduce: 3, autofit: null},
+    {reduce: 4, autofit: null},
+    {reduce: 6, autofit: null}
+  ],
+
+  /** Object to hold parameters related to 1up mode */
+  onePage: {
+    /** @type {AutoFitValues} */
+    autofit: 'auto',
+  },
+
+  /** Object to hold parameters related to 2up mode */
+  twoPage: {
+    /** Width of cover */
+    coverInternalPadding: 0,
+    /** Padding outside of cover */
+    coverExternalPadding: 0,
+    /** Width of book spine  $$$ consider sizing based on book length */
+    bookSpineDivWidth: 64,
+    /** @type {AutoFitValues} */
+    autofit: 'auto'
+  },
+
+  onePageMinBreakpoint: 800,
+
+  bookTitle: '',
+  /** @type {string} */
+  bookUrl: null,
+  /** @type {string} */
+  bookUrlText: null,
+  /** @type {string} */
+  bookUrlTitle: null,
+  enableBookTitleLink: true,
+  /**
+   * @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
+   * appear to use 639-2/B ? But I don't think that's a guarantee). See
+   * https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ) */
+  bookLanguage: null,
+
+  /**
+   * @type {Array<{label: string, value: *, extraValueClass: string?}>}
+   * Fields used to populate the info window
+   * @example [
+   *   {label: 'Title', value: 'Open Library BookReader Presentation'},
+   *   {label: 'Author', value: 'Internet Archive'},
+   *   {label: 'Demo Info', value: 'This demo shows how one could use BookReader with their own content.'},
+   * ]
+   **/
+  metadata: [],
+  /** @type {string} */
+  thumbnail: null,
+  /** @type {string} */
+  bookUrlMoreInfo: null,
+
+  /** Experimental Controls (eg b/w) */
+  enableExperimentalControls: false,
+
+  /** CSS selectors */
+  /** Where BookReader mounts to */
+  el: '#BookReader',
+
+  /** @type {'lr' | 'rl'} Page progression */
+  pageProgression: 'lr',
+
+  /** The PPI the book is scanned at **/
+  ppi: 500,
+
+  /** Should image downloads be blocked */
+  protected: false,
+
+  /**
+   * Settings for individual plugins. Note they have to be imported first.
+   * WIP: Most plugins just put their options anywhere in this global options file,
+   * but going forward we'll keep them here.
+   **/
+  plugins: {
+    /** @type {import('../plugins/plugin.text_selection.js').TextSelectionPluginOptions} */
+    textSelection: null,
+  },
+
+  /**
+   * Any variables you want to define. If an option has a StringWithVars type, or
+   * has something like `{{server}}/foo.com` in its value, these variables replace
+   * the `{{foo}}`.
+   * @type { {[var_name: string]: any } }
+   */
+  vars: {},
+
+  /**
+   * @type {Array<[PageData, PageData]|[PageData]>}
+   * Data is a simple way to populate the bookreader
+   *
+   * Example:
+   * ```
+   * [
+   *   // Each child is a spread
+   *   [
+   *     {
+   *       width: 123,
+   *       height: 123,
+   *       // Optional: If not provided, include a getPageURI
+   *       uri: 'https://archive.org/image.jpg',
+   *       // Optional: Shown instead of leaf number if present.
+   *       pageNum: '1'
+   *     },
+   *     {width: 123, height: 123, uri: 'https://archive.org/image2.jpg', pageNum: '2'},
+   *   ]
+   * ],
+   * ```
+   *
+   * Note if URI is omitted, a custom getPageURI can be provided. This allows the page
+   * URI to the result of a function, which allows for things such as dynamic
+   * page scaling.
+   */
+  data: [],
+
+  /** Advanced methods for page rendering */
+  /** @type {() => number} */
+  getNumLeafs: null,
+  /** @type {(index: number) => number} */
+  getPageWidth: null,
+  /** @type {(index: number) => number} */
+  getPageHeight: null,
+  /** @type {(index: number, reduce: number, rotate: number) => *} */
+  getPageURI: null,
+
+  /**
+   * @type {(index: number) => 'L' | 'R'}
+   * Return which side, left or right, that a given page should be displayed on
+   */
+  getPageSide: null,
+
+  /**
+   * @type {(pindex: number) => [number, number]}
+   * This function returns the left and right indices for the user-visible
+   * spread that contains the given index.  The return values may be
+   * null if there is no facing page or the index is invalid.
+   */
+  getSpreadIndices: null,
+
+  /** @type {(index: number) => string} */
+  getPageNum: null,
+  /** @type {(index: number) => *} */
+  getPageProp: null,
+  /** @type {(index: number) => number} */
+  leafNumToIndex: null,
+
+  /**
+   * @type {(frameWidth: number|string, frameHeight: number|string, viewParams) => *}
+   * Optional: if present, and embed code will be shown in the share dialog
+   */
+  getEmbedCode: null,
+
+  controls: {
+    bookLeft: {
+      visible: true,
+      label: 'Flip left',
+      className: 'book_left',
+      iconClassName: 'left-arrow'
+    },
+    bookRight: {
+      visible: true,
+      label: 'Flip right',
+      className: 'book_right',
+      iconClassName: 'left-arrow hflip'
+    },
+    onePage: {
+      visible: true,
+      label: 'One-page view',
+      className: 'onepg',
+      iconClassName: 'onepg'
+    },
+    twoPage: {
+      visible: true,
+      label: 'Two-page view',
+      className: 'twopg',
+      iconClassName: 'twopg'
+    },
+    thumbnail: {
+      visible: true,
+      label: 'Thumbnail view',
+      className: 'thumb',
+      iconClassName: 'thumb'
+    },
+    viewmode: {
+      visible: true,
+      className: 'viewmode',
+      excludedModes: [],
+    },
+    zoomOut: {
+      visible: true,
+      label: 'Zoom out',
+      className: 'zoom_out',
+      iconClassName: 'magnify'
+    },
+    zoomIn: {
+      visible: true,
+      label: 'Zoom in',
+      className: 'zoom_in',
+      iconClassName: 'magnify plus'
+    },
+    fullScreen: {
+      visible: true,
+      label: 'Toggle fullscreen',
+      className: 'full',
+      iconClassName: 'fullscreen'
+    },
+  },
+
+  /**
+   * @type {Boolean}
+   * Optional: if true, starts in fullscreen mode
+   */
+  startFullscreen: false,
+
+  /**
+   * @type {Boolean}
+   * On init, by default, we want to handle resizing bookreader
+   * when browser window changes size (inc. `orientationchange` event)
+   * toggle off if you want to handle this outside of bookreader
+   */
+  autoResize: true,
+
+  /**
+   * @type {Boolean}
+   * On init, by default, we want to use srcSet for images
+   */
+  useSrcSet: false,
+};
+
+/** @typedef {'width' | 'height' | 'auto' | 'none'} AutoFitValues */
+
+/**
+ * @typedef {object} ReductionFactor
+ * @property {number} reduce
+ * @property {AutoFitValues} [autofit] If set, the corresponding reduction factors
+ * are what will be used when the user tries to autofit by width/height.
+ */
+
+/**
+ * @typedef {Object} PageData
+ * @property {number} width
+ * @property {number} height
+ * @property {string} [uri] If not provided, include a getPageURI
+ * @property {PageNumString} [pageNum] Shown instead of leaf number if present
+ * @property {LeafNum} [leafNum] Sometimes specified in Internet Archive books
+ * @property {number} [ppi] The resolution of the page if different from {@see BookReaderOptions.ppi}
+ * @property {'L' | 'R'} [pageSide] PRIVATE; computed automatically
+ * @property {boolean} [viewable=true] Set false if page is not viewable. Displays a dummy preview image.
+ * @property {number} [unviewablesStart] PRIVATE; index where the chunk of unviewable pages started
+ *
+ * Note if URI is omitted, a custom getPageURI can be provided. This allows the page
+ * URI to the result of a function, which allows for things such as dynamic
+ * page scaling.
+ */
+
+/** @typedef {typeof DEFAULT_OPTIONS} BookReaderOptions */
+

package/src/BookReader/utils/HTMLDimensionsCacher.js

@@ -0,0 +1,44 @@
+// @ts-check
+import { debounce } from '../utils';
+
+/**
+ * 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/classes.js

@@ -0,0 +1,36 @@
+/**
+ * Exposes a function from one class (FromClass) to another (ToClass), in such a way
+ * that if the ToClass's method is overridden, the FromClass's method is also overridden.
+ * WARNING: This modifies FromClass' prototype! So FromClasses cannot be shared between
+ * different ToClasses.
+ * @param {new () => TFrom} FromClass the class to get the method from
+ * @param {keyof TFrom} fromMethod the method's name in FromClass
+ * @param {function(TFrom): TTo} fromTransform how to get the TTo `this` to use when setting the method on TFrom
+ * @param {new () => TTo} ToClass the class to add the method to
+ * @param {string} toMethod the name of the method to add to TTo (likely will be equal to fromMethod)
+ * @param {function(TTo): TFrom} toTransform how to get the TFrom this to use when calling the new method
+ * @template TFrom type of FromClass for type-checking/autocomplete
+ * @template TTo type of ToClass for type-checking/autocomplete
+ */
+export function exposeOverrideable(FromClass, fromMethod, fromTransform, ToClass, toMethod, toTransform) {
+  // Wrapper function needed to "capture" the current version of fromMethod
+  let wrapper = (fn => {
+    return function () {
+      return fn.apply(toTransform(this), arguments);
+    };
+  })(FromClass.prototype[fromMethod]);
+
+  Object.defineProperty(ToClass.prototype, toMethod, {
+    get() { return wrapper; },
+    set(overrideFn) {
+      // overrideFn expects `this` to be ToClass, so ensure as such
+      // But we can also call this method from FromClass; need to ensure
+      // it's always called with a ToClass
+      FromClass.prototype[fromMethod] = function () {
+        const newThis = this instanceof FromClass ? fromTransform(this) : this;
+        return overrideFn.apply(newThis, arguments);
+      };
+      wrapper = overrideFn;
+    }
+  });
+}

package/src/BookReader/utils.js

@@ -0,0 +1,240 @@
+/**
+ * Bind mouse handlers
+ * Disable mouse click to avoid selected/highlighted page images
+ * @param {JQuery} jObject
+ */
+export function disableSelect(jObject) {
+  // $$$ check here for right-click and don't disable.  Also use jQuery style
+  //     for stopping propagation. See https://bugs.edge.launchpad.net/gnubook/+bug/362626
+  jObject.bind('mousedown', () => false);
+  // Special hack for IE7
+  jObject[0].onselectstart = () => false;
+}
+
+/**
+ * @param {number} value
+ * @param {number} min
+ * @param {number} max
+ * @return {number}
+ */
+export function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Given value and maximum, calculate a percentage suitable for CSS
+ * @param {number} value
+ * @param {number} max
+ * @return {string}
+ */
+export function cssPercentage(value, max) {
+  return ((value / max) * 100) + '%';
+}
+
+/**
+ * @param {*} value
+ * @param {Array} array
+ * @return {boolean}
+ */
+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}
+ */
+export function getIFrameDocument(iframe) {
+// Adapted from http://xkr.us/articles/dom/iframe-document/
+  const outer = iframe.contentWindow || iframe.contentDocument;
+  return outer.document || outer;
+}
+
+/**
+ * @param {string} str
+ * @return {string}
+ */
+export function escapeHTML(str) {
+  return str.replace(/&/g,'&')
+    .replace(/>/g,'>')
+    .replace(/</g,'&lt;')
+    .replace(/"/g,'&quot;');
+}
+
+/**
+ * Decodes a URI component and converts '+' to ' '
+ * @param {string} value
+ * @return {string}
+ */
+export function decodeURIComponentPlus(value) {
+  return decodeURIComponent(value).replace(/\+/g, ' ');
+}
+
+/**
+ * Encodes a URI component and converts ' ' to '+'
+ * @param {string|number|boolean} value
+ * @return {string};
+ */
+export function encodeURIComponentPlus(value) {
+  return encodeURIComponent(value).replace(/%20/g, '+');
+}
+
+/**
+ * @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 {T} func
+ * @param {number} wait
+ * @param {boolean} immediate
+ * @return {T}
+ */
+export function debounce(func, wait, immediate) {
+  let timeout;
+  return function() {
+    const context = this;
+    const args = arguments;
+    const later = () => {
+      timeout = null;
+      if (!immediate) func.apply(context, args);
+    };
+    const callNow = immediate && !timeout;
+    clearTimeout(timeout);
+    timeout = setTimeout(later, wait);
+    if (callNow) func.apply(context, args);
+  };
+}
+
+/**
+ * @template T
+ * Throttle function
+ * @see https://remysharp.com/2010/07/21/throttling-function-calls
+ * @param {T} fn
+ * @param {number} threshold
+ * @param {boolean} delay
+ * @return {T}
+ */
+export function throttle(fn, threshold, delay) {
+  threshold || (threshold = 250);
+  let last;
+  let deferTimer;
+  if (delay) last = +new Date;
+  return function () {
+    const context = this;
+    const now = +new Date;
+    const args = arguments;
+    if (last && now < last + threshold) {
+      // hold on to it
+      clearTimeout(deferTimer);
+      deferTimer = setTimeout(() => {
+        last = now;
+        fn.apply(context, args);
+      }, threshold);
+    } else {
+      last = now;
+      fn.apply(context, args);
+    }
+  };
+}
+
+/**
+ * FIXME we need a better way to do this :/ This is not automatically poly-filled by
+ * core-js https://github.com/zloirock/core-js/issues/354
+ * @param {Window} window
+ */
+export function polyfillCustomEvent(window) {
+  if (typeof window.CustomEvent === "function") return false;
+  window.CustomEvent = PolyfilledCustomEvent;
+}
+
+/**
+ * https://caniuse.com/customevent has issues on older browsers where it can't be
+ * called as a constructor, so we have to use older methods.
+ * @param {String} eventName
+ * @return {CustomEvent}
+ */
+export function PolyfilledCustomEvent(eventName, {bubbles = false, cancelable = false, detail = null} = {}) {
+  const event = document.createEvent('CustomEvent');
+  event.initCustomEvent(eventName, bubbles, cancelable, detail);
+  return event;
+}
+
+/*
+ * Returns the number pixels something should be rendered at to be ~1n on the users
+ * screen when measured with a ruler.
+ */
+export function calcScreenDPI() {
+  const el = document.createElement('div');
+  el.style.width = '1in';
+  document.body.appendChild(el);
+  const dpi = el.offsetWidth;
+  document.body.removeChild(el);
+
+  // Do you believe in magic... numbers? We tested on some devices, and the displayed
+  // size of `width: 1in` was less than desired. On @pezvi's mac, it was ~75% ; on
+  // @cdrini's laptop it was ~85%. Since we want to avoid things appearing too small,
+  // let's just use a multiplier of 1.25
+  const screenDPI = dpi * 1.25;
+  // 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);
+}