@internetarchive/bookreader 5.0.0-11 → 5.0.0-110

package/README.md

@@ -2,7 +2,7 @@
 
 ![Build Status](https://github.com/internetarchive/bookreader/actions/workflows/node.js.yml/badge.svg?branch=master) [![codecov](https://codecov.io/gh/internetarchive/bookreader/branch/master/graph/badge.svg)](https://codecov.io/gh/internetarchive/bookreader)
 
-**Disclaimer: BookReader v5 is currently in beta. It's stable enough for production use (and is what is being used on archive.org), but there will be some breaking changes in the next ~month or so to public BookReader APIs.**
+**Disclaimer: BookReader v5 is currently in beta. It is stable enough for production use and is actively deployed on archive.org. Future updates while in v5 beta may introduce breaking changes to public BookReader APIs, although these will be noted in the CHANGELOG.**
 
 
 <p align="center">
@@ -123,7 +123,7 @@ A peek in how to use/extend core functionality:
     - plugin.url.js - automatically updates the browser url
     - plugin.resume.js - uses cookies to remember the current page
     - plugin.vendor-fullscreen.js - replaces fullscreen mode with vendor native fullscreen
-    - see plugin directory for current plugin files ()[https://github.com/internetarchive/bookreader/tree/master/src/plugins]
+    - see [plugin directory for current plugin files](https://github.com/internetarchive/bookreader/tree/master/src/plugins)
 
 ### Embedding BookReader in an iFrame
 
@@ -147,7 +147,18 @@ The Fragment Change message is sent to the parent window when the embedded BookR
 
 The source JavaScript is written in ES6 (located in the `src/js` directory) and in ES5 (located in `BookReader`). `npm run serve-dev` starts an auto-reloading dev server, that builds js/css that has been edited at `localhost:8000`.
 
-Until the next major version bump, we have to store the build files inside the repo to maintain backwards compatibility. Please _DO NOT_ include these files in your PR. Anything in the `BookReader/` directory should not be committed.
+### Developing icons
+To see local icon package changes in bookreader, you'll need to install core-js into the icon package and link into bookreader.
+
+Let's use `icon-share` as an example.
+1.  Confirm your icon package is working properly in the iaux-icons demo
+2.  Navigate to your icon package (`iaux-icons/packages/icon-share`) and run command: `npm install core-js`
+    -  You shouldn't need to commit any of these core-js changes
+3.  From within your icon package directory run command: `npm link`
+    -  You can use the command `npm ls -g` to confirm your local package now appears in the registry
+4.  Navigate to `/bookreader` and run command: `npm link @internetarchive/icon-share`
+    -  You can use the command `npm ls |grep icon-share` to confirm icon-share is now a link to your local directory
+5. You may now start a local server to see your changes by running command: `npm run serve-dev`
 
 ## Releases
 

package/jsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "es6",
+    "moduleResolution": "node",
+    "experimentalDecorators": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "src/**/*.js",
+    "tests/**/*.js",
+  ],
+  "exclude": [
+    "node_modules",
+    "BookReader"
+  ]
+}

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "@internetarchive/bookreader",
-  "version": "5.0.0-11",
+  "version": "5.0.0-110",
   "description": "The Internet Archive BookReader.",
+  "type": "module",
+  "files": [
+    "BookReader/",
+    "src/",
+    "jsconfig.json"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/internetarchive/bookreader.git"
@@ -9,7 +15,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "module": "src/BookNavigator/BookNavigator.js",
+  "module": "src/ia-bookreader/ia-bookreader.js",
   "keywords": [
     "online",
     "bookreader",
@@ -25,92 +31,108 @@
   "homepage": "https://github.com/internetarchive/bookreader#readme",
   "private": false,
   "dependencies": {
-    "@internetarchive/ia-activity-indicator": "^0.0.1",
-    "@internetarchive/ia-icons": "^1.2.2",
-    "@internetarchive/ia-menu-slider": "^1.0.0",
-    "@internetarchive/ia-sharing-options": "^0.1.2",
-    "@internetarchive/icon-bookmark": "^1.1.3",
-    "@internetarchive/icon-collapse-sidebar": "^1.1.0",
-    "@internetarchive/icon-edit-pencil": "1.1.5",
-    "@internetarchive/icon-magnify-minus": "^1.2.3",
-    "@internetarchive/icon-magnify-plus": "^1.2.3",
-    "@internetarchive/icon-search": "^1.2.3",
-    "@internetarchive/modal-manager": "^0.1.0",
-    "lit-element": "^2.4.0",
-    "lit-html": "^1.3.0"
-  },
-  "devDependencies": {
-    "@babel/core": "7.13.16",
-    "@babel/preset-env": "7.13.15",
-    "@open-wc/testing": "^2.5.33",
-    "@open-wc/testing-karma": "^4.0.9",
-    "@types/jest": "26.0.23",
-    "babel-loader": "8.2.2",
-    "codecov": "3.8.1",
-    "concurrently": "6.0.2",
-    "core-js": "3.11.0",
-    "cpx2": "3.0.0",
-    "eslint": "7.25.0",
-    "eslint-plugin-testcafe": "0.2.1",
-    "http-server": "0.12.3",
-    "iso-language-codes": "1.0.8",
-    "jest": "26.6.3",
-    "jquery": "1.11.3",
+    "@internetarchive/bergamot-translator": "^0.4.9-ia.1",
+    "@internetarchive/ia-activity-indicator": "0.0.6",
+    "@internetarchive/ia-item-navigator": "2.2.2",
+    "@internetarchive/icon-bookmark": "^1.4.0",
+    "@internetarchive/icon-close": "1.4.0",
+    "@internetarchive/icon-dl": "^1.4.0",
+    "@internetarchive/icon-edit-pencil": "^1.4.1",
+    "@internetarchive/icon-ia-logo": "1.4.0",
+    "@internetarchive/icon-magnify-minus": "^1.4.0",
+    "@internetarchive/icon-magnify-plus": "^1.4.0",
+    "@internetarchive/icon-search": "^1.4.0",
+    "@internetarchive/icon-toc": "^1.4.0",
+    "@internetarchive/icon-visual-adjustment": "^1.4.0",
+    "@internetarchive/modal-manager": "2.0.5",
+    "@internetarchive/shared-resize-observer": "^0.2.0",
+    "interactjs": "^1.10.18",
+    "iso-language-codes": "2.0.0",
+    "jquery": "3.6.1",
     "jquery-colorbox": "1.6.4",
     "jquery-ui": "1.12.1",
     "jquery-ui-touch-punch": "0.2.3",
     "jquery.browser": "0.1.0",
-    "jquery.mmenu": "5.6.5",
-    "karma-coverage": "^2.0.3",
-    "live-server": "1.2.1",
-    "node-fetch": "2.6.1",
-    "regenerator-runtime": "0.13.7",
-    "sass": "1.32.11",
-    "sinon": "10.0.0",
-    "soundmanager2": "2.97.20170602",
-    "svgo": "2.3.0",
-    "testcafe": "1.14.0",
-    "webpack": "5.35.0",
-    "webpack-cli": "4.6.0"
+    "lit": "2.8.0",
+    "soundmanager2": "2.97.20170602"
+  },
+  "devDependencies": {
+    "@babel/core": "7.29.0",
+    "@babel/eslint-parser": "7.28.6",
+    "@babel/plugin-proposal-class-properties": "7.18.6",
+    "@babel/plugin-proposal-decorators": "7.29.0",
+    "@babel/preset-env": "7.29.2",
+    "@iiif/presentation-2": "^1.0.4",
+    "@iiif/presentation-3": "^2.1.3",
+    "@open-wc/testing-helpers": "3.0.1",
+    "@types/jest": "30.0.0",
+    "@webcomponents/webcomponentsjs": "^2.6.0",
+    "babel-loader": "10.1.1",
+    "concurrently": "9.0.1",
+    "core-js": "3.49.0",
+    "cpx2": "8.0.0",
+    "eslint": "7.32.0",
+    "eslint-plugin-no-jquery": "^2.7.0",
+    "eslint-plugin-testcafe": "0.2.1",
+    "http-server": "14.1.1",
+    "hypothesis": "^1.1627.0",
+    "jest": "30.3.0",
+    "jest-environment-jsdom": "30.3.0",
+    "live-server": "1.2.2",
+    "regenerator-runtime": "0.14.1",
+    "sass": "1.98.0",
+    "sinon": "21.0.3",
+    "svgo": "4.0.1",
+    "testcafe": "3.7.4",
+    "testcafe-browser-provider-browserstack": "1.15.2",
+    "webpack": "5.105.4",
+    "webpack-cli": "7.0.2"
   },
   "jest": {
+    "testEnvironment": "jsdom",
+    "transformIgnorePatterns": [
+      "node_modules/(?!(sinon|lit-html|lit-element|lit|@lit|@lit-labs|@internetarchive|@open-wc)/)"
+    ],
+    "moduleNameMapper": {
+      "^@/(.*)$": "<rootDir>/$1"
+    },
     "setupFiles": [
-      "./src/jquery-wrapper.js"
+      "./src/jquery-wrapper.js",
+      "./tests/jest/setup.js"
     ],
     "roots": [
       "<rootDir>/src/",
-      "<rootDir>/tests/"
-    ],
-    "testPathIgnorePatterns": [
-      "<rootDir>/tests/e2e/",
-      "<rootDir>/tests/karma/"
-    ],
-    "coverageDirectory": "<rootDir>/coverage-jest"
+      "<rootDir>/tests/jest/"
+    ]
   },
   "scripts": {
-    "preversion": "npm run test && node scripts/preversion.js",
+    "preversion": "node scripts/preversion.js",
     "version": "node scripts/version.js",
     "postversion": "node scripts/postversion.js",
-    "build": "npm run clean && npm run build-js && npm run build-css && npm run build-assets",
+    "build": "npm run clean && npx concurrently --group npm:build-js npm:build-css npm:build-assets npm:build-hypothesis npm:build-bergamot",
     "build-assets": "npx cpx \"src/assets/**/*\" BookReader && npx svgo -f BookReader/icons && npx svgo -f BookReader/images",
     "build-assets:watch": "npx cpx --watch --verbose \"src/assets/**/*\" BookReader",
+    "build-bergamot": "npx cpx \"node_modules/@internetarchive/bergamot-translator/worker/*\" BookReader/",
+    "build-bergamot:watch": "npx cpx --watch \"node_modules/@internetarchive/bergamot-translator/worker/*\" BookReader/",
+    "build-hypothesis": "npx cpx \"node_modules/hypothesis/**/*\" BookReader/hypothesis",
+    "build-hypothesis:watch": "npx cpx --watch --verbose \"node_modules/hypothesis/**/*\" BookReader/hypothesis",
     "build-js": "npx webpack",
     "build-js:watch": "npx webpack --mode=development --watch",
-    "build-css": "npx sass --no-source-map ./src/css/BookReader.scss ./BookReader/BookReader.css",
-    "build-css:watch": "npx sass --watch --no-source-map ./src/css/BookReader.scss ./BookReader/BookReader.css",
+    "build-css": "npx sass --silence-deprecation=import --no-source-map ./src/css/BookReader.scss ./BookReader/BookReader.css",
+    "build-css:watch": "npx sass --silence-deprecation=import --watch --no-source-map ./src/css/BookReader.scss ./BookReader/BookReader.css",
     "clean": "rm -r BookReader/ || true",
-    "lint": "npx eslint src/ tests/ *.js",
-    "lint:fix": "npx eslint --fix src/ tests/ *.js",
-    "serve": "npx http-server . --port 8000",
-    "serve-live": "npx live-server . --port 8000 --watch=index.html,BookReader,BookReaderDemo",
-    "serve-dev": "npm run build-css && npx concurrently --kill-others npm:serve-live npm:build-*:watch",
-    "test": "npm run test-jest && npm run test-karma",
-    "test:e2e": "npm run build && env BASE_URL=http://127.0.0.1:8000/BookReaderDemo/ npx testcafe",
-    "test:e2e:dev": "env BASE_URL=http://127.0.0.1:8000/BookReaderDemo/ npx testcafe --live --dev",
-    "test-jest:watch": "npx jest --watch",
-    "test-jest": "npx jest --coverage --colors",
-    "test-karma": "npx karma start --coverage",
-    "test-karma:watch": "npx karma start --auto-watch=true --single-run=false",
-    "codecov": "npx codecov"
+    "lint": "npx eslint src/ tests/ *.js *.cjs",
+    "lint:fix": "npx eslint --fix src/ tests/ *.js *.cjs",
+    "serve": "npx http-server . --port=8000",
+    "serve-live": "node scripts/live-server.js",
+    "serve-dev": "env NODE_ENV='development' npm run build-css && env NODE_ENV='development' npx concurrently --kill-others npm:serve-live npm:build-*:watch",
+    "test": "npx jest --coverage --colors",
+    "test:watch": "npx jest --watch",
+    "test:e2e": "npm run build && npx testcafe",
+    "test:e2e:dev": "npx testcafe --live --dev",
+    "DOCS:update:test-deps": "If CI succeeds, these should be good to update",
+    "update:test-deps": "npm i @babel/eslint-parser@latest @open-wc/testing-helpers@latest @types/jest@latest eslint@7 eslint-plugin-testcafe@latest jest@latest jest-environment-jsdom@latest sinon@latest testcafe@latest",
+    "DOCS:update:build-deps": "These can cause strange changes, so do an npm run build + check file size (git diff --stat), and check the site is as expected",
+    "update:build-deps": "npm i @babel/core@latest @babel/preset-env@latest @babel/plugin-proposal-class-properties@latest @babel/plugin-proposal-decorators@latest babel-loader@latest core-js@latest regenerator-runtime@latest sass@latest svgo@latest webpack@latest webpack-cli@latest"
   }
 }

package/src/BookReader/BookModel.js

@@ -4,11 +4,6 @@ import { clamp } from './utils.js';
 /** @typedef {import('./options.js').PageData} PageData */
 /** @typedef {import('../BookReader.js').default} BookReader */
 
-// URI to display when a page is not viewable.
-// TODO Render configurable html for the user instead.
-// FIXME Don't reference files on archive.org
-const UNVIEWABLE_PAGE_URI = '/bookreader/static/preview-default.png';
-
 /**
  * Contains information about the Book/Document independent of the way it is
  * being rendering. Nothing here should reference e.g. the mode, zoom, etc.
@@ -23,42 +18,15 @@ export class BookModel {
     this.br = br;
     this.reduceSet = br.reduceSet;
     this.ppi = br.options?.ppi ?? DEFAULT_OPTIONS.ppi;
+    /** @type {'lr' | 'rl'} Page progression */
+    this.pageProgression = br.options?.pageProgression ?? DEFAULT_OPTIONS.pageProgression;
 
     /** @type {{width: number, height: number}} memoize storage */
     this._medianPageSize = null;
-    /** @deprecated @type {{width: number, height: number}} memoize storage */
-    this._medianPageSizePixels = null;
     /** @type {[PageData[], number]} */
     this._getDataFlattenedCached = null;
   }
 
-  /**
-   * @deprecated Use getMedianPageSizeInches
-   * Memoized
-   * @return {{width: number, height: number}}
-   */
-  getMedianPageSize() {
-    if (this._medianPageSizePixels) {
-      return this._medianPageSizePixels;
-    }
-
-    // A little expensive but we just do it once
-    const widths = [];
-    const heights = [];
-    for (let i = 0; i < this.getNumLeafs(); i++) {
-      widths.push(this.getPageWidth(i));
-      heights.push(this.getPageHeight(i));
-    }
-
-    widths.sort();
-    heights.sort();
-    this._medianPageSizePixels = {
-      width: widths[Math.floor(widths.length / 2)],
-      height: heights[Math.floor(heights.length / 2)]
-    };
-    return this._medianPageSizePixels;
-  }
-
   /** Get median width/height of page in inches. Memoized for performance. */
   getMedianPageSizeInches() {
     if (this._medianPageSize) {
@@ -72,12 +40,12 @@ export class BookModel {
       heights.push(page.heightInches);
     }
 
-    widths.sort();
-    heights.sort();
+    widths.sort((a, b) => a - b);
+    heights.sort((a, b) => a - b);
 
     this._medianPageSize = {
       width: widths[Math.floor(widths.length / 2)],
-      height: heights[Math.floor(heights.length / 2)]
+      height: heights[Math.floor(heights.length / 2)],
     };
     return this._medianPageSize;
   }
@@ -187,7 +155,17 @@ export class BookModel {
    */
   // eslint-disable-next-line no-unused-vars
   getPageURI(index, reduce, rotate) {
-    return !this.getPageProp(index, 'viewable', true) ? UNVIEWABLE_PAGE_URI : this.getPageProp(index, 'uri');
+    if (!this.getPageProp(index, 'viewable', true)) {
+      const uri = this.br.options.unviewablePageURI;
+      if (uri.startsWith('.')) {
+        // It's a relative path, so make it relative to the images path
+        return this.br.options.imagesBaseURL + uri;
+      } else {
+        return uri;
+      }
+    } else {
+      return this.getPageProp(index, 'uri');
+    }
   }
 
   /**
@@ -226,7 +204,7 @@ export class BookModel {
    * @return {[PageIndex, PageIndex]} eg [0, 1]
    */
   getSpreadIndices(pindex) {
-    if (this.br.pageProgression == 'rl') {
+    if (this.pageProgression == 'rl') {
       return this.getPageSide(pindex) == 'R' ? [pindex + 1, pindex] : [pindex, pindex - 1];
     } else {
       return this.getPageSide(pindex) == 'L' ? [pindex, pindex + 1] : [pindex - 1, pindex];
@@ -296,6 +274,7 @@ export class BookModel {
    * @param {number} [arg0.end] exclusive
    * @param {boolean} [arg0.combineConsecutiveUnviewables] Yield only first unviewable
    * of a chunk of unviewable pages instead of each page
+   * @return {Generator<PageModel>}
    */
   * pagesIterator({ start = 0, end = Infinity, combineConsecutiveUnviewables = false } = {}) {
     start = Math.max(0, start);
@@ -379,8 +358,9 @@ export class PageModel {
    * @param {PageIndex} index
    */
   constructor(book, index) {
-    // TODO: Get default from config
-    this.ppi = book._getDataProp(index, 'ppi', book.ppi);
+    // Values less than 10 cause the UI to not work correctly
+    const pagePPI = book._getDataProp(index, 'ppi', book.ppi);
+    this.ppi = Math.max(pagePPI < 10 ? book.ppi : pagePPI, 10);
     this.book = book;
     this.index = index;
     this.width = book.getPageWidth(index);
@@ -437,6 +417,42 @@ export class PageModel {
     return this.findNext();
   }
 
+  /** @type {PageModel | null} */
+  get left() {
+    return this.book.pageProgression === 'lr' ? this.prev : this.next;
+  }
+
+  /** @type {PageModel | null} */
+  get right() {
+    return this.book.pageProgression === 'lr' ? this.next : this.prev;
+  }
+
+  /**
+   * @type {{left: PageModel | null, right: PageModel | null}}
+   */
+  get spread() {
+    return {
+      left: this.pageSide === 'L' ? this : this.left,
+      right: this.pageSide === 'R' ? this : this.right,
+    };
+  }
+
+  /**
+   * @param {number} pages
+   */
+  goLeft(pages) {
+    const newIndex = this.book.pageProgression === 'lr' ? this.index - pages : this.index + pages;
+    return this.book.getPage(newIndex);
+  }
+
+  /**
+   * @param {number} pages
+   */
+  goRight(pages) {
+    const newIndex = this.book.pageProgression === 'lr' ? this.index + pages : this.index - pages;
+    return this.book.getPage(newIndex);
+  }
+
   /**
    * @param {number} reduce
    * @param {number} rotate
@@ -445,6 +461,15 @@ export class PageModel {
     return this.book.getPageURI(this.index, reduce, rotate);
   }
 
+  /**
+   * Return the asserted page number for this page, or, if one is not
+   * present, the n-prefixed page index.
+   * @returns {PageNumString}
+   */
+  getPageNum() {
+    return this.book.getPageNum(this.index);
+  }
+
   /**
    * Returns the srcset with correct URIs or void string if out of range
    * @param {number} reduce
@@ -468,7 +493,7 @@ export class PageModel {
    * @param {object} [arg0]
    * @param {boolean} [arg0.combineConsecutiveUnviewables] Whether to only yield the first page
    * of a series of unviewable pages instead of each page
-   * @return {PageModel|void}
+   * @return {PageModel|undefined}
    */
   findNext({ combineConsecutiveUnviewables = false } = {}) {
     return this.book
@@ -480,7 +505,7 @@ export class PageModel {
    * @param {object} [arg0]
    * @param {boolean} [arg0.combineConsecutiveUnviewables] Whether to only yield the first page
    * of a series of unviewable pages instead of each page
-   * @return {PageModel|void}
+   * @return {PageModel|undefined}
    */
   findPrev({ combineConsecutiveUnviewables = false } = {}) {
     if (this.index == 0) return undefined;
@@ -498,17 +523,38 @@ export class PageModel {
       return new PageModel(this.book, this.index - 1);
     }
   }
+
+  /**
+   * @param {object} [arg0]
+   * @param {boolean} [arg0.combineConsecutiveUnviewables] Whether to only yield the first page
+   * of a series of unviewable pages instead of each page
+   * @return {PageModel|undefined}
+   */
+  findLeft({ combineConsecutiveUnviewables = false } = {}) {
+    return this.book.pageProgression === 'lr' ? this.findPrev({ combineConsecutiveUnviewables }) : this.findNext({ combineConsecutiveUnviewables });
+  }
+
+  /**
+   * @param {object} [arg0]
+   * @param {boolean} [arg0.combineConsecutiveUnviewables] Whether to only yield the first page
+   * of a series of unviewable pages instead of each page
+   * @return {PageModel|undefined}
+   */
+  findRight({ combineConsecutiveUnviewables = false } = {}) {
+    return this.book.pageProgression === 'lr' ? this.findNext({ combineConsecutiveUnviewables }) : this.findPrev({ combineConsecutiveUnviewables });
+  }
 }
 
 // There are a few main ways we can reference a specific page in a book:
 /**
  * @typedef {string} PageNumString
- * Possible values: /^n?\d+$/. Example: 'n7', '18'
- * Not necessarily unique
+ * The way page numbers are usually displayed in the UI. Either
+ * an asserted page number if the book has one (e.g. '18', or 'A-1'),
+ * or the n-prefixed 0-based index (e.g. 'n7')
  */
 /**
  * @typedef {number} LeafNum
- * No clue if 0 or 1 indexed or consecutive; generally from IA book info.
+ * Internal number to IA scans. Can be 0 or 1 indexed. Unclear it it's consecutive.
  */
 /**
  * @typedef {string} PageString