@internetarchive/bookreader 5.0.0-95 → 5.0.0-97

package/src/BookReader/options.js

@@ -0,0 +1,387 @@
+// @ts-check
+/** @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,
+  /** min zoom in columns */
+  thumbMinZoomColumns: 2,
+  /** max zoom out columns */
+  thumbMaxZoomColumns: 8,
+
+  /** @type {number | 'fast' | 'slow'} speed for flip animation */
+  flipSpeed: 400,
+
+  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} 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
+   * 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 {Partial<import('../plugins/plugin.archive_analytics.js').ArchiveAnalyticsPlugin['options'>]}*/
+    archiveAnalytics: null,
+    /** @type {Partial<import('../plugins/plugin.autoplay.js').AutoplayPlugin['options'>]}*/
+    autoplay: null,
+    /** @type {Partial<import('../plugins/plugin.chapters.js').ChaptersPlugin['options']>} */
+    chapters: null,
+    /** @type {Partial<import('../plugins/plugin.iiif.js').IiifPlugin['options']>} */
+    iiif: null,
+    /** @type {Partial<import('../plugins/plugin.resume.js').ResumePlugin['options']>} */
+    resume: null,
+    /** @type {Partial<import('../plugins/search/plugin.search.js').SearchPlugin['options']>} */
+    search: null,
+    /** @type {Partial<import('../plugins/plugin.text_selection.js').TextSelectionPlugin['options']>} */
+    textSelection: null,
+    /** @type {Partial<import('../plugins/tts/plugin.tts.js').TtsPlugin['options']>} */
+    tts: 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: [],
+
+  /** @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) => 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
+   */
+  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}
+   * will show logo at fullscreen mode
+  */
+  enableFSLogoShortcut: 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,
+
+  /**
+   * @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
+ * - 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
+ * @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 */
+
+/**
+ * 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

@@ -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;
+    },
+  });
+}