Update BR mustache + add first BR unit tests

cdrini · cdrini · commit bc95911bbb6c · 2025-05-26T19:40:05.000+02:00
diff --git a/dev-server/documents/html/bookreader.mustache b/dev-server/documents/html/bookreader.mustache
@@ -17,16 +17,17 @@
     </p>
 
     <!-- JS dependencies -->
-    <script src="http://localhost:8000/BookReader/jquery-3.js"></script>
+    <!-- IA uses the @next version of BR -->
+    <script src="https://unpkg.com/@internetarchive/bookreader@next/BookReader/jquery-3.js"></script>
 
     <!-- BookReader and any plugins -->
-    <link rel="stylesheet" href="http://localhost:8000/BookReader/BookReader.css" />
-    <script src="http://localhost:8000/BookReader/BookReader.js"></script>
-    <script src="http://localhost:8000/BookReader/plugins/plugin.text_selection.js"></script>
+    <link rel="stylesheet" href="https://unpkg.com/@internetarchive/bookreader@next/BookReader/BookReader.css" />
+    <script src="https://unpkg.com/@internetarchive/bookreader@next/BookReader/BookReader.js"></script>
+    <script src="https://unpkg.com/@internetarchive/bookreader@next/BookReader/plugins/plugin.text_selection.js"></script>
 
     <!-- BookReader wrapper web component -->
     <script type="module"
-      src="http://localhost:8000/BookReader/ia-bookreader-bundle.js"></script>
+      src="https://unpkg.com/@internetarchive/bookreader@next/BookReader/ia-bookreader-bundle.js"></script>
 
     <style>
       html {
diff --git a/src/annotator/anchoring/BookReader.ts b/src/annotator/anchoring/BookReader.ts
@@ -75,12 +75,12 @@ export async function describe(
 
   const pageContainer: HTMLElement = textLayer.closest('.BRpagecontainer')!;
   const pageIndex = parseFloat(pageContainer.dataset.index!);
-  const pageLabel = pageContainer.dataset.label!;
+  const pageNum = pageContainer.dataset.pageNum!;
 
   const pageSelector: PageSelector = {
     type: 'PageSelector',
     index: pageIndex,
-    label: pageLabel || `n${pageIndex}`,
+    label: pageNum || `n${pageIndex}`,
   };
 
   return [quote, pageSelector];
@@ -153,7 +153,7 @@ async function pollUntilTruthy<T>(
   fn: () => T,
   { timeout = 1000 },
 ): Promise<T | undefined> {
-  return new Promise((resolve, reject) => {
+  return new Promise(resolve => {
     const start = Date.now();
     const interval = setInterval(() => {
       const val = fn();
diff --git a/src/annotator/integrations/BookReader.ts b/src/annotator/integrations/BookReader.ts
@@ -1,16 +1,17 @@
 import debounce from 'lodash.debounce';
-import { TinyEmitter } from 'tiny-emitter';
 
+import { EventEmitter } from '../../shared/event-emitter';
 import type { BookReader } from '../../types/BookReader';
 import type {
   Anchor,
   AnnotationData,
   AnnotationTool,
   Annotator,
   Integration,
+  IntegrationEvents,
   SidebarLayout,
 } from '../../types/annotator';
-import { PageSelector, Selector } from '../../types/api';
+import type { PageSelector, Selector } from '../../types/api';
 import { anchor, canDescribe, describe } from '../anchoring/BookReader';
 import { TextRange } from '../anchoring/text-range';
 
@@ -30,7 +31,10 @@ export function isBookReader() {
 /**
  * Integration that works with PDF.js
  */
-export class BookReaderIntegration extends TinyEmitter implements Integration {
+export class BookReaderIntegration
+  extends EventEmitter<IntegrationEvents>
+  implements Integration
+{
   private _annotator: Annotator;
   private _br: BookReader;
   private _debouncedUpdate: () => void;
@@ -118,7 +122,7 @@ export class BookReaderIntegration extends TinyEmitter implements Integration {
   }
 
   // This method (re-)anchors annotations when pages are rendered and destroyed.
-  _update = async () => {
+  _update = () => {
     const refreshAnnotations: AnnotationData[] = [];
 
     // For pages that are no longer visible, we want to
@@ -132,22 +136,24 @@ export class BookReaderIntegration extends TinyEmitter implements Integration {
         continue;
       }
 
+      // If it's a placeholder and its page is now visible, we want to re-anchor
       const placeholder = anchor.highlights[0].closest(
-        '.BRannotationPlaceholder',
+        '.BRhypothesisPlaceholder',
       );
-      // If it's a placeholder and its page is now visible, we want to re-anchor
       if (placeholder) {
         const pageSelector = anchor.target.selector?.find(
           s => s.type === 'PageSelector',
         ) as PageSelector;
         if (!pageSelector) {
-          throw new Error('No page selector found');
+          // Legacy annotation without a page selector; skip?
+          console.warn('No page selector found');
+          continue;
         }
 
-        const pageContainer = this._br.refs.$br.find(
+        const pageContainer = this.contentContainer().querySelector(
           `.BRpagecontainer[data-index="${pageSelector.index}"]`,
         );
-        if (pageContainer.length) {
+        if (pageContainer) {
           delete anchor.region;
           placeholder.remove();
           anchor.highlights.splice(0, anchor.highlights.length);
@@ -159,7 +165,8 @@ export class BookReaderIntegration extends TinyEmitter implements Integration {
         }
       }
 
-      // Now it's not a placeholder; if it's page has been removed, then we need to re-anchor (potentially creating a placeholder)
+      // Ok, not a placeholder; if its page has been removed, then we need to
+      // re-anchor (potentially creating a placeholder)
       const notInDom = anchor.highlights.some(
         highlight => !document.body.contains(highlight),
       );
@@ -181,7 +188,7 @@ export class BookReaderIntegration extends TinyEmitter implements Integration {
    * Return the scrollable element which contains the document content.
    */
   contentContainer(): HTMLElement {
-    return this._br.refs.$br.find('.BRcontainer')?.[0] as HTMLElement;
+    return this._br.refs.$br[0] as HTMLElement;
   }
 
   sideBySideActive() {
@@ -209,7 +216,7 @@ export class BookReaderIntegration extends TinyEmitter implements Integration {
       throw new Error('No page selector found');
     }
 
-    if (this._br.activeMode.name == 'thumb') {
+    if (this._br.activeMode.name === 'thumb') {
       this._br.switchMode('2up', { suppressFragmentChange: true });
       await delay(50);
     }
diff --git a/src/annotator/integrations/test/BookReader-test.js b/src/annotator/integrations/test/BookReader-test.js
@@ -0,0 +1,168 @@
+import { BookReaderIntegration, isBookReader } from '../BookReader';
+
+describe('annotator/integrations/BookReader', () => {
+  describe('isBookReader', () => {
+    beforeEach(() => {
+      delete window.br;
+    });
+
+    it('returns true in BookReader', () => {
+      window.br = {};
+      assert.isTrue(isBookReader());
+    });
+
+    it('returns false in other applications', () => {
+      assert.isFalse(isBookReader());
+    });
+  });
+
+  describe('BookReaderIntegration', () => {
+    /** @type {HTMLDivElement} */
+    let brRoot;
+    /** @type {BookReaderIntegration} */
+    let brIntegration;
+    /** @type {import('../../../types/annotator').Annotator} */
+    let fakeAnnotator;
+    /** @type {import('../../../types/annotator').Anchor} */
+    let fakeAnchor;
+
+    beforeEach(() => {
+      brRoot = document.createElement('div');
+      fakeAnchor = {
+        highlights: [],
+        target: {
+          selector: [
+            {
+              type: 'TextQuoteSelector',
+              prefix: 'prefix',
+              suffix: 'suffix',
+              exact: 'exact',
+            },
+            {
+              type: 'PageSelector',
+              index: 14,
+              label: 'x',
+            },
+          ],
+        },
+      };
+      fakeAnnotator = {
+        anchor: sinon.stub(),
+        anchors: [],
+        anchoring: null,
+      };
+
+      window.br = {
+        options: {
+          bookTitle: 'Dummy Title',
+          bookUri: 'dummy-uri',
+        },
+        refs: {
+          $br: {
+            0: brRoot,
+          },
+        },
+        activeMode: {
+          name: '1up',
+        },
+        on: sinon.stub(),
+        off: sinon.stub(),
+        jumpToIndex: sinon.stub(),
+        switchMode: sinon.stub(),
+        plugins: {
+          textSelection: {
+            options: { enabled: true },
+          },
+        },
+      };
+
+      brIntegration = new BookReaderIntegration(fakeAnnotator);
+    });
+
+    afterEach(() => {
+      delete window.br;
+    });
+
+    it('re-anchors placeholders if page now visible', () => {
+      const [placeholderHighlight, anchor] = createPlaceholderHighlight(
+        brRoot,
+        fakeAnchor,
+        fakeAnnotator,
+      );
+      brIntegration._update();
+
+      // Page is not attached, so placeholder should remain
+      assert.isNotNull(placeholderHighlight.parentNode);
+      assert.lengthOf(anchor.highlights, 1);
+      assert.equal(anchor.highlights[0], placeholderHighlight);
+      assert.notCalled(fakeAnnotator.anchor);
+
+      // Attach the page
+      createFakePage(brRoot);
+      brIntegration._update();
+
+      // Now the page is visible, so placeholder should be removed
+      assert.isNull(placeholderHighlight.parentNode);
+      assert.lengthOf(anchor.highlights, 0);
+      assert.calledOnce(fakeAnnotator.anchor);
+      assert.calledWith(fakeAnnotator.anchor, anchor.annotation);
+    });
+
+    it('re-anchors annotations if their page is removed', () => {
+      const [highlight, anchor] = createNonPlaceholderHighlight(
+        brRoot,
+        fakeAnchor,
+        fakeAnnotator,
+      );
+
+      // We haven't created the page, so this is like if the page has been removed
+      brIntegration._update();
+
+      // The highlight should have been removed
+      assert.isNull(highlight.parentNode);
+      assert.lengthOf(anchor.highlights, 0);
+    });
+
+    it('switches mode when anchoring in thumb mode ', async () => {
+      window.br.activeMode.name = 'thumb';
+
+      await brIntegration.scrollToAnchor(fakeAnchor);
+
+      assert.calledOnce(window.br.switchMode);
+      assert.calledOnce(window.br.jumpToIndex);
+    });
+  });
+});
+
+function createFakePage(brRoot) {
+  const fakePage = document.createElement('div');
+  fakePage.classList.add('BRpagecontainer');
+  fakePage.setAttribute('data-index', '14');
+  brRoot.appendChild(fakePage);
+  return fakePage;
+}
+
+function createPlaceholderHighlight(brRoot, fakeAnchor, fakeAnnotator) {
+  const placeholderHighlight = document.createElement('div');
+  placeholderHighlight.classList.add('BRhypothesisPlaceholder');
+  brRoot.appendChild(placeholderHighlight);
+  const anchor = {
+    ...fakeAnchor,
+    highlights: [placeholderHighlight],
+  };
+  fakeAnnotator.anchors = [anchor];
+  return [placeholderHighlight, anchor];
+}
+
+function createNonPlaceholderHighlight(brRoot, fakeAnchor, fakeAnnotator) {
+  const highlight = document.createElement('div');
+  const innerText = document.createElement('div');
+  highlight.appendChild(innerText);
+  brRoot.appendChild(highlight);
+  const anchor = {
+    ...fakeAnchor,
+    highlights: [highlight],
+  };
+  fakeAnnotator.anchors = [anchor];
+  return [highlight, anchor];
+}
diff --git a/src/types/BookReader.ts b/src/types/BookReader.ts
@@ -1,8 +1,6 @@
 /**
- * BookReader doesn't quite have types, so create a stub here
- *
- * Note that the definitions here are not complete, they only include properties
- * that the client uses.
+ * Stub BookReader types. Note that the definitions here are not complete, they
+ * only include properties that the client uses.
  */
 
 export type BookReader = {
@@ -28,7 +26,7 @@ export type BookReader = {
     options?: { suppressFragmentChange: boolean },
   ): void;
 
-  _plugins: {
+  plugins: {
     textSelection:
       | undefined
       | {
@@ -40,5 +38,4 @@ export type BookReader = {
 type JQuery<T> = {
   [index: number]: T;
   length: number;
-  find: (selector: string) => JQuery<T>;
 };
