Merge pull request #1399 from cdrini/feature/hypothesis

cdrini · web-flow · commit 9972dc5b33ea · 2025-04-30T15:42:23.000-04:00
Extend BR to work correctly with Hypothesis
diff --git a/.gitignore b/.gitignore
@@ -4,4 +4,7 @@ node_modules/
 coverage*/
 .env
 
+# Eventually ignore this directory entirely
+BookReader/hypothesis
+
 .vscode
diff --git a/BookReaderDemo/IADemoBr.js b/BookReaderDemo/IADemoBr.js
@@ -57,6 +57,7 @@ const initializeBookReader = (brManifest) => {
     // urlTrackedParams: ['page', 'search', 'mode'],
     /* End url plugin */
     enableBookTitleLink: false,
+    bookUri: `https://archive.org/details/${ocaid}`,
     bookUrlText: null,
     startFullscreen: openFullImmersionTheater,
     // leaving this option commented out bc we change given user agent on archive.org
diff --git a/BookReaderDemo/demo-internetarchive.html b/BookReaderDemo/demo-internetarchive.html
@@ -30,6 +30,7 @@
     <script src="../BookReader/plugins/plugin.resume.js"></script>
     <script src="../BookReader/plugins/plugin.archive_analytics.js"></script>
     <script src="../BookReader/plugins/plugin.text_selection.js"></script>
+    <script src="../BookReader/plugins/plugin.experiments.js"></script>
 
     <script type="module" src="../BookReader/ia-bookreader-bundle.js"></script>
 
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -59,6 +59,7 @@
     "eslint-plugin-no-jquery": "^2.7.0",
     "eslint-plugin-testcafe": "^0.2.1",
     "http-server": "14.1.1",
+    "hypothesis": "^1.1627.0",
     "interactjs": "^1.10.18",
     "iso-language-codes": "1.1.0",
     "jest": "29.7.0",
@@ -100,9 +101,11 @@
     "preversion": "npm run test && node scripts/preversion.js",
     "version": "node scripts/version.js",
     "postversion": "node scripts/postversion.js",
-    "build": "npm run clean && npx concurrently --group npm:build-js npm:build-css npm:build-assets",
+    "build": "npm run clean && npx concurrently --group npm:build-js npm:build-css npm:build-assets npm:build-hypothesis",
     "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-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",
diff --git a/src/BookNavigator/book-navigator.js b/src/BookNavigator/book-navigator.js
@@ -10,6 +10,7 @@ import BookmarksProvider from './bookmarks/bookmarks-provider.js';
 import SharingProvider from './sharing.js';
 import ViewableFilesProvider from './viewable-files.js';
 import iaLogo from './assets/ia-logo.js';
+import { sortBy } from '../BookReader/utils.js';
 /** @typedef {import('@/src/BookReader.js').default} BookReader */
 
 const events = {
@@ -51,7 +52,20 @@ export class BookNavigator extends LitElement {
     this.isAdmin = false;
     this.lendingInitialized = false;
     this.lendingStatus = {};
-    this.menuProviders = {};
+    this.menuProviders = {
+      /** @type {BookmarksProvider} */
+      bookmarks: null,
+      /** @type {SearchProvider} */
+      search: null,
+      /** @type {DownloadProvider} */
+      downloads: null,
+      /** @type {VisualAdjustmentProvider} */
+      visualAdjustments: null,
+      /** @type {SharingProvider} */
+      share: null,
+      /** @type {ViewableFilesProvider} */
+      volumes: null,
+    };
     this.menuShortcuts = [];
     this.signedIn = false;
     /** @type {ModalManager} */
@@ -73,6 +87,10 @@ export class BookNavigator extends LitElement {
       'chapters',
       'search',
       'bookmarks',
+      'downloads',
+      'visualAdjustments',
+      'share',
+      'experiments',
     ];
   }
 
@@ -313,14 +331,20 @@ export class BookNavigator extends LitElement {
    * Sets order of menu and emits custom event when done
    */
   updateMenuContents() {
-    const {
-      search, downloads, visualAdjustments, share, bookmarks, volumes, chapters,
-    } = this.menuProviders;
-    const availableMenus = [volumes, chapters, search, bookmarks, visualAdjustments, share].filter((menu) => !!menu);
+    const availableMenus = sortBy(
+      Object.entries(this.menuProviders)
+        .filter(([id, menu]) => !!menu)
+        .filter(([id, menu]) => {
+          return id === 'downloads' ? this.shouldShowDownloadsMenu() : true;
+        }),
+      ([id, menu]) => {
+        const index = this.shortcutOrder.indexOf(id);
+        return index === -1 ? this.shortcutOrder.length : index;
+      },
+    ).map(([id, menu]) => menu);
 
     if (this.shouldShowDownloadsMenu()) {
-      downloads?.update(this.downloadableTypes);
-      availableMenus.splice(-2, 0, downloads);
+      this.menuProviders.downloads?.update(this.downloadableTypes);
     }
 
     const event = new CustomEvent(
@@ -387,11 +411,13 @@ export class BookNavigator extends LitElement {
    * the id in each iteration over the shortcutOrder array.
    */
   sortMenuShortcuts() {
-    this.menuShortcuts = this.shortcutOrder.reduce((shortcuts, id) => {
-      const menu = this.menuShortcuts.find((m) => m.id === id);
-      if (menu) { shortcuts.push(menu); }
-      return shortcuts;
-    }, []);
+    this.menuShortcuts = sortBy(
+      this.menuShortcuts,
+      (shortcut) => {
+        const index = this.shortcutOrder.indexOf(shortcut.id);
+        return index === -1 ? this.shortcutOrder.length : index;
+      },
+    );
   }
 
   emitMenuShortcutsUpdated() {
diff --git a/src/BookNavigator/visual-adjustments/visual-adjustments-provider.js b/src/BookNavigator/visual-adjustments/visual-adjustments-provider.js
@@ -45,7 +45,7 @@ export default class VisualAdjustmentsProvider {
     this.icon = html`<ia-icon-visual-adjustment style="width: var(--iconWidth); height: var(--iconHeight);"></ia-icon-visual-adjustment>`;
     this.label = 'Visual Adjustments';
     this.menuDetails = this.updateOptionsCount();
-    this.id = 'adjustment';
+    this.id = 'visualAdjustments';
     this.component = html`
       <ia-book-visual-adjustments
         .options=${visualAdjustmentOptions}
diff --git a/src/BookReader.js b/src/BookReader.js
@@ -702,14 +702,28 @@ BookReader.prototype.trigger = function(name, props = this) {
   $(document).trigger(eventName, props);
 };
 
-BookReader.prototype.bind = function(name, callback) {
+BookReader.prototype.on = function(name, callback) {
   $(document).on('BookReader:' + name, callback);
 };
 
-BookReader.prototype.unbind = function(name, callback) {
+BookReader.prototype.off = function(name, callback) {
   $(document).off('BookReader:' + name, callback);
 };
 
+/**
+ * @deprecated Use .on and .off instead
+ */
+BookReader.prototype.bind = function(name, callback) {
+  return this.on(name, callback);
+};
+
+/**
+ * @deprecated Use .on and .off instead
+ */
+BookReader.prototype.unbind = function(name, callback) {
+  return this.off(name, callback);
+};
+
 /**
  * Resizes based on the container width and height
  */
@@ -1105,7 +1119,7 @@ BookReader.prototype.getPrevReadMode = function(mode) {
 
 /**
  * Switches the mode (eg 1up 2up thumb)
- * @param {number}
+ * @param {number|'1up' | '2up' | 'thumb'}
  * @param {object} [options]
  * @param {boolean} [options.suppressFragmentChange = false]
  * @param {boolean} [options.onInit = false] - this
@@ -1118,6 +1132,18 @@ BookReader.prototype.switchMode = function(
     pageFound = false,
   } = {},
 ) {
+  if (typeof mode === 'string') {
+    mode = {
+      '1up': this.constMode1up,
+      '2up': this.constMode2up,
+      'thumb': this.constModeThumb,
+    }[mode];
+  }
+
+  if (!mode) {
+    throw new Error(`Invalid mode: ${mode}`);
+  }
+
   // Skip checks before init() complete
   if (this.init.initComplete) {
     if (mode === this.mode) {
@@ -1324,7 +1350,7 @@ BookReader.prototype.updateFirstIndex = function(
   // If there's an initial search we stop suppressing global URL changes
   // when local suppression ends
   // This seems to correctly handle multiple calls during mode/1up
-  if (this.plugins.search.options.initialSearchTerm && !suppressFragmentChange) {
+  if (this.plugins.search?.options.initialSearchTerm && !suppressFragmentChange) {
     this.suppressFragmentChange = false;
   }
 
diff --git a/src/BookReader/BookModel.js b/src/BookReader/BookModel.js
@@ -461,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
@@ -539,12 +548,13 @@ export class PageModel {
 // 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
diff --git a/src/BookReader/Mode1Up.js b/src/BookReader/Mode1Up.js
@@ -6,6 +6,8 @@ import { DragScrollable } from './DragScrollable.js';
 /** @typedef {import('./BookModel.js').PageIndex} PageIndex */
 
 export class Mode1Up {
+  name = '1up'
+
   /**
    * @param {BookReader} br
    * @param {BookModel} bookModel
diff --git a/src/BookReader/Mode2Up.js b/src/BookReader/Mode2Up.js
@@ -6,6 +6,8 @@ import { DragScrollable } from './DragScrollable.js';
 /** @typedef {import('./BookModel.js').PageIndex} PageIndex */
 
 export class Mode2Up {
+  name = '2up';
+
   /**
    * @param {BookReader} br
    * @param {BookModel} bookModel
diff --git a/src/BookReader/ModeThumb.js b/src/BookReader/ModeThumb.js
@@ -9,6 +9,8 @@ import { DragScrollable } from './DragScrollable.js';
 /** @typedef {JQuery} $lazyLoadImgPlaceholder * jQuery element with data attributes: leaf, reduce */
 
 export class ModeThumb {
+  name = 'thumb'
+
   /**
    * @param {BookReader} br
    * @param {BookModel} bookModel
diff --git a/src/BookReader/PageContainer.js b/src/BookReader/PageContainer.js
@@ -18,7 +18,10 @@ export class PageContainer {
     this.$container = $('<div />', {
       'class': `BRpagecontainer ${page ? `pagediv${page.index}` : 'BRemptypage'}`,
       css: { position: 'absolute' },
-    }).attr('data-side', page?.pageSide);
+    })
+      .attr('data-side', page?.pageSide)
+      .attr('data-index', page?.index)
+      .attr('data-page-num', page?.getPageNum());
 
     if (isProtected) {
       this.$container.append($('<div class="BRscreen" />'));
diff --git a/src/BookReader/options.js b/src/BookReader/options.js
@@ -97,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
diff --git a/src/BookReader/utils.js b/src/BookReader/utils.js
@@ -298,3 +298,16 @@ export function parseAnimationSpeed(speed) {
   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;
+  });
+}
diff --git a/src/assets/images/hypothesis.ico b/src/assets/images/hypothesis.ico
diff --git a/src/css/_TextSelection.scss b/src/css/_TextSelection.scss
@@ -8,6 +8,7 @@
     // Make it so right-clicking on "blank" part of text layer sends events to the image (for saving)
     pointer-events: none;
     cursor: text;
+    mix-blend-mode: multiply;
 }
 
 .BRparagraphElement {
@@ -58,7 +59,8 @@
 
 // Hide text layer for performance during zooming & scrolling
 .BRsmooth-zooming, .BRscrolling-active {
-    .BRpagecontainer:not(.BRpagecontainer--hasSelection) .BRtextLayer {
+    // If the text layer has an annotation, don't hide it
+    .BRpagecontainer:not(.BRpagecontainer--hasSelection):not(:has(hypothesis-highlight)) .BRtextLayer {
         display: none;
     }
 }
diff --git a/src/plugins/plugin.experiments.js b/src/plugins/plugin.experiments.js
diff --git a/tests/jest/BookNavigator/book-navigator.test.js b/tests/jest/BookNavigator/book-navigator.test.js
diff --git a/tests/jest/BookReader/PageContainer.test.js b/tests/jest/BookReader/PageContainer.test.js
diff --git a/webpack.config.js b/webpack.config.js
