@internetarchive/bookreader 5.0.0-90 → 5.0.0-92

package/BookReaderDemo/IADemoBr.js

@@ -45,6 +45,23 @@ BookReader.optionOverrides.imagesBaseURL = '/BookReader/images/';
 const initializeBookReader = (brManifest) => {
   console.log('initializeBookReader', brManifest);
 
+  const {bookPath, subPrefix} = brManifest.data.brOptions;
+  let path = bookPath;
+  const subPrefixWithSlash = `/${subPrefix}`;
+  if (bookPath.length - bookPath.lastIndexOf(subPrefixWithSlash) == subPrefixWithSlash.length) {
+    path = bookPath.substr(0, bookPath.length - subPrefixWithSlash.length);
+  }
+
+  const searchInsideUrl = '//{{server}}/fulltext/inside.php?' + [
+    'item_id={{bookId|urlencode}}',
+    'doc={{subPrefix|urlencode}}',
+    'q={{query|urlencode}}',
+    // This endpoint doesn't expect the path to be url encoded
+    `path=${encodeURIComponent(path).replace(/%2F/g, '/')}`,
+    'pre_tag={{preTag|urlencode}}',
+    'post_tag={{postTag|urlencode}}',
+  ].join('&');
+
   const options = {
     el: '#BookReader',
     /* Url plugin - IA uses History mode for URL */
@@ -59,7 +76,6 @@ const initializeBookReader = (brManifest) => {
     enableBookTitleLink: false,
     bookUrlText: null,
     startFullscreen: openFullImmersionTheater,
-    initialSearchTerm: searchTerm ? searchTerm : '',
     // leaving this option commented out bc we change given user agent on archive.org
     // onePage: { autofit: <?=json_encode($this->ios ? 'width' : 'auto')?> },
     showToolbar: getFromUrl('options.showToolbar', 'false') === 'true',
@@ -70,6 +86,18 @@ const initializeBookReader = (brManifest) => {
     /* End multiple volumes */
     enableBookmarks: true, // turn this on
     enableFSLogoShortcut: true,
+
+    // TMP: To be replaced once BookReaderJSIA is updated to provide
+    // these in the right spot.
+    plugins: {
+      search: {
+        enabled: true,
+        initialSearchTerm: searchTerm ? searchTerm : '',
+        searchInsideUrl,
+        preTag: brManifest.data.brOptions.searchInsidePreTag,
+        postTag: brManifest.data.brOptions.searchInsidePostTag,
+      },
+    },
   };
 
   // we want to show item as embedded when ?ui=embed is in URI

package/BookReaderDemo/ia-multiple-volumes-manifest.js

@@ -5,7 +5,6 @@ const extraVolOptions = {
   "enableBookTitleLink": false,
   "bookUrlText": null,
   "startFullscreen": false,
-  "initialSearchTerm": null,
   "onePage": {
     "autofit": "auto"
   },

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+# 5.0.0-92
+- Refactor: Migrate search plugin to BookReaderPlugin system @cdrini
+  - Breaking changes:
+    - Search options are now nested under the plugin (eg `searchInsideUrl` → `options.plugins.search.searchInsideUrl`), and mostly no longer include the `search` prefix; specifically:
+      - `searchInsidePreTag`, `searchInsidePostTag` → `options.plugins.search.preTag` and `postTag`
+      - `searchInsideUrl` is now a `StringWithVars` and supports including `vars` from the root options, e.g. `searchInsideUrl: "https://{{server}}/search_endpoint?q={{query|urlencode}}"` . It also has access to the `preTag` and `postTag` from the options. Note this allows the search inside URL to now be fully customizable from the options, and is no longer hard-coded internally to Internet Archive specific logic. 
+      - `initialSearchTerm` → `options.plugins.search.initialSearchTerm`
+      - `searchInsideProtocol` → deprecated in favour of variables in `searchInsideUrl`
+  - Internal search related methods/properties are now nested in the `SearchPlugin` and no longer accessible from the root bookreader object. Notable exception: `br.search` is still made available for convenience.
+      - Moved: `searchResults`, `searchXHR`, `searchView`, `cancelSearchRequest`, `BRSearchCallback`, `updateSearchHilites`, `removeSearchResults`, `removeSearchHilites`, `searchHighlightVisible`
+
+
+# 5.0.0-91
+- Refactor: Migrate ChaptersPlugin to BookReaderPlugin system @cdrini
+  - Breaking changes:
+    - Options moved:
+        - `options.olHost` → `options.plugins.chapters.olHost`
+        - `options.enableChaptersPlugin` → `options.plugins.chapters.enabled`
+        - Note `table_of_contents` _did not_ move; that is still root-level
+    - All chapters state/methods moved from `BookReader` to `BookReader.plugins.chapters`. Full list:
+        - eg `BookReader._chapters*` has been moved to `BookReader.plugins.chapters._*`
+  - See https://github.com/internetarchive/bookreader/pull/1381
+- Feature: TextSelectionPlugin now supports `protected` option @cdrini
+- Feature: New option for ChaptersPlugin for explicit `openLibraryId` @cdrini
+- Fix: No longer error when book ends on unviewable page @cdrini
+- Fix: ReadAloud no longer jumps to top of page every time it scrolls @cdrini
+- Fix: Fix various ReadAloud issues -- ReadAloud stuttering, not stopping, getting stuck, etc. @cdrini
+
 # 5.0.0-90
 - Fix: Festival TTS not working @cdrini
 

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">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@internetarchive/bookreader",
-  "version": "5.0.0-90",
+  "version": "5.0.0-92",
   "description": "The Internet Archive BookReader.",
   "repository": {
     "type": "git",

package/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';
+/** @typedef {import('@/src/BookReader.js').default} BookReader */
 
 const events = {
   menuUpdated: 'menuUpdated',
@@ -183,7 +184,9 @@ export class BookNavigator extends LitElement {
       providers.downloads = new DownloadProvider(this.baseProviderConfig);
     }
 
-    if (this.bookreader.options.enableSearch) {
+    // Note plugins will never be null-ish in runtime, but some of the unit tests
+    // stub BR with a nullish value there.
+    if (this.bookreader.options.plugins?.search?.enabled) {
       providers.search = new SearchProvider({
         ...this.baseProviderConfig,
         /**
@@ -193,7 +196,7 @@ export class BookNavigator extends LitElement {
          */
         onProviderChange: (brInstance = null, searchUpdates = {}) => {
           if (brInstance) {
-            /* refresh br instance reference */
+            /** @type {BookReader} refresh br instance reference */
             this.bookreader = brInstance;
           }
 

package/src/BookNavigator/search/search-provider.js

@@ -1,7 +1,10 @@
+// @ts-check
 import { html, nothing } from 'lit';
 import '@internetarchive/icon-search/icon-search';
 import './search-results';
 /** @typedef {import('@/src/plugins/search/plugin.search.js').SearchInsideMatch} SearchInsideMatch */
+/** @typedef {import('@/src/plugins/search/plugin.search.js').SearchInsideResults} SearchInsideResults */
+/** @typedef {import('@/src/BookReader.js').default} BookReader */
 
 let searchState = {
   query: '',
@@ -99,11 +102,14 @@ export default class SearchProvider {
     this.bookreader.search(searchState.query);
   }
 
+  /**
+   * @param {CustomEvent<{props: {instance: BookReader, results: SearchInsideResults}}>} event
+   */
   onSearchRequestError(event, errorType = 'default') {
-    const { detail: { props = {} } } = event;
-    const { instance = null } = props;
+    const { detail: { props } } = event;
+    const { instance, results } = props;
     if (instance) {
-      /* keep bookreader instance reference up-to-date */
+      /** @type {BookReader} keep bookreader instance reference up-to-date */
       this.bookreader = instance;
     }
     const errorMessages = {
@@ -114,7 +120,7 @@ export default class SearchProvider {
     };
 
     const messageToShow = errorMessages[errorType] ?? errorMessages.default;
-    searchState.query = instance?.searchResults?.q || '';
+    searchState.query = results?.q || '';
     searchState.results = [];
     searchState.resultsCount = 0;
     searchState.queryInProgress = false;
@@ -137,7 +143,7 @@ export default class SearchProvider {
   }
 
   searchCanceledInMenu() {
-    this.bookreader?.cancelSearchRequest();
+    this.bookreader._plugins.search.cancelSearchRequest();
   }
 
   onSearchResultsCleared() {
@@ -149,7 +155,7 @@ export default class SearchProvider {
       errorMessage: '',
     };
     this.updateMenu({ openMenu: false });
-    this.bookreader?.searchView?.clearSearchFieldAndResults(false);
+    this.bookreader._plugins.search.searchView.clearSearchFieldAndResults(false);
     if (this.bookreader.urlPlugin) {
       this.updateSearchInUrl();
     }
@@ -198,6 +204,6 @@ export default class SearchProvider {
    * @param {{ detail: {match: SearchInsideMatch} }} param0
    */
   onSearchResultsClicked({ detail }) {
-    this.bookreader._searchPluginGoToResult(detail.match.matchIndex);
+    this.bookreader._plugins.search.jumpToMatch(detail.match.matchIndex);
   }
 }

package/src/BookNavigator/sharing.js

@@ -10,7 +10,7 @@ export default class SharingProvider {
   }) {
     const { identifier, creator, title } = item?.metadata;
     const creatorToUse = Array.isArray(creator) ? creator[0] : creator;
-    const subPrefix = bookreader.options.subPrefix || '';
+    const subPrefix = bookreader.subPrefix || '';
     const label = `Share this book`;
     this.icon = html`${iauxShareIcon}`;
     this.label = label;

package/src/BookReader/BookModel.js

@@ -274,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);
@@ -483,7 +484,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
@@ -495,7 +496,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;
@@ -518,7 +519,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}
    */
   findLeft({ combineConsecutiveUnviewables = false } = {}) {
     return this.book.pageProgression === 'lr' ? this.findPrev({ combineConsecutiveUnviewables }) : this.findNext({ combineConsecutiveUnviewables });
@@ -528,7 +529,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}
    */
   findRight({ combineConsecutiveUnviewables = false } = {}) {
     return this.book.pageProgression === 'lr' ? this.findNext({ combineConsecutiveUnviewables }) : this.findPrev({ combineConsecutiveUnviewables });

package/src/BookReader/Toolbar/Toolbar.js

@@ -59,6 +59,11 @@ export class Toolbar {
       $titleSectionEl.append(br.bookUrlText || br.bookTitle);
     }
 
+    // Call _bindNavigationHandlers on the plugins
+    for (const plugin of Object.values(br._plugins)) {
+      plugin._configureToolbar(br.refs.$BRtoolbar);
+    }
+
     // const $hamburger = br.refs.$BRtoolbar.find('BRtoolbarHamburger');
     return br.refs.$BRtoolbar;
   }

package/src/BookReader/options.js

@@ -141,17 +141,21 @@ export const DEFAULT_OPTIONS = {
    * but going forward we'll keep them here.
    **/
   plugins: {
-    /** @type {import('../plugins/plugin.archive_analytics.js').ArchiveAnalyticsPlugin['options']}*/
+    /** @type {Partial<import('../plugins/plugin.archive_analytics.js').ArchiveAnalyticsPlugin['options'>]}*/
     archiveAnalytics: null,
-    /** @type {import('../plugins/plugin.autoplay.js').AutoplayPlugin['options']}*/
+    /** @type {Partial<import('../plugins/plugin.autoplay.js').AutoplayPlugin['options'>]}*/
     autoplay: null,
-    /** @type {import('../plugins/plugin.iiif.js').IiifPlugin['options']} */
+    /** @type {Partial<import('../plugins/plugin.chapters.js').ChaptersPlugin['options']>} */
+    chapters: null,
+    /** @type {Partial<import('../plugins/plugin.iiif.js').IiifPlugin['options']>} */
     iiif: null,
-    /** @type {import('../plugins/plugin.resume.js').ResumePlugin['options']} */
+    /** @type {Partial<import('../plugins/plugin.resume.js').ResumePlugin['options']>} */
     resume: null,
-    /** @type {import('../plugins/plugin.text_selection.js').TextSelectionPlugin['options']} */
+    /** @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 {import('../plugins/tts/plugin.tts.js').TtsPlugin['options']} */
+    /** @type {Partial<import('../plugins/tts/plugin.tts.js').TtsPlugin['options']>} */
     tts: null,
   },
 

package/src/BookReader.js

@@ -44,7 +44,7 @@ import { NAMED_REDUCE_SETS } from './BookReader/ReduceSet';
 
 /**
  * BookReader
- * @param {BookReaderOptions} options
+ * @param {Partial<BookReaderOptions>} overrides
  * TODO document all options properties
  * @constructor
  */
@@ -70,8 +70,12 @@ BookReader.PLUGINS = {
   archiveAnalytics: null,
   /** @type {typeof import('./plugins/plugin.autoplay.js').AutoplayPlugin | null}*/
   autoplay: null,
+  /** @type {typeof import('./plugins/plugin.chapters.js').ChaptersPlugin | null}*/
+  chapters: null,
   /** @type {typeof import('./plugins/plugin.resume.js').ResumePlugin | null}*/
   resume: null,
+  /** @type {typeof import('./plugins/search/plugin.search.js').SearchPlugin | null}*/
+  search: null,
   /** @type {typeof import('./plugins/plugin.text_selection.js').TextSelectionPlugin | null}*/
   textSelection: null,
   /** @type {typeof import('./plugins/tts/plugin.tts.js').TtsPlugin | null}*/
@@ -80,7 +84,7 @@ BookReader.PLUGINS = {
 
 /**
  * @param {string} pluginName
- * @param {typeof import('./BookReaderPlugin.js').BookReaderPlugin} plugin
+ * @param {new (...args: any[]) => import('./BookReaderPlugin.js').BookReaderPlugin} plugin
  */
 BookReader.registerPlugin = function(pluginName, plugin) {
   if (BookReader.PLUGINS[pluginName]) {
@@ -116,10 +120,25 @@ BookReader.prototype.setup = function(options) {
   // Store the options used to setup bookreader
   this.options = options;
 
+  /** @type {import('@/src/BookNavigator/book-navigator.js').BookNavigator} */
+  this.shell;
+
+  // Base server used by some api calls
+  /** @deprecated */
+  this.bookId = options.bookId;
+  /** @deprecated */
+  this.server = options.server;
+  /** @deprecated */
+  this.subPrefix = options.subPrefix;
+  /** @deprecated */
+  this.bookPath = options.bookPath;
+
   // Construct the usual plugins first to get type hints
   this._plugins = {
     archiveAnalytics: BookReader.PLUGINS.archiveAnalytics ? new BookReader.PLUGINS.archiveAnalytics(this) : null,
     autoplay: BookReader.PLUGINS.autoplay ? new BookReader.PLUGINS.autoplay(this) : null,
+    chapters: BookReader.PLUGINS.chapters ? new BookReader.PLUGINS.chapters(this) : null,
+    search: BookReader.PLUGINS.search ? new BookReader.PLUGINS.search(this) : null,
     resume: BookReader.PLUGINS.resume ? new BookReader.PLUGINS.resume(this) : null,
     textSelection: BookReader.PLUGINS.textSelection ? new BookReader.PLUGINS.textSelection(this) : null,
     tts: BookReader.PLUGINS.tts ? new BookReader.PLUGINS.tts(this) : null,
@@ -148,12 +167,14 @@ BookReader.prototype.setup = function(options) {
     }
   }
 
+  if (this._plugins.search?.options.enabled) {
+    // Expose the search method for convenience / backward compat
+    this.search = this._plugins.search.search.bind(this._plugins.search);
+  }
+
   /** @type {number} @deprecated some past iterations set this */
   this.numLeafs = undefined;
 
-  /** Overridden by plugin.search.js */
-  this.enableSearch = false;
-
   /**
    * Store viewModeOrder states
    * @var {boolean}
@@ -441,23 +462,24 @@ BookReader.prototype.initParams = function() {
   }
 
   // Check for Search plugin
-  if (this.options.enableSearch) {
+  if (this._plugins.search?.options.enabled) {
+    const sp = this._plugins.search;
     // Go to first result only if no default or URL page
-    this.options.goToFirstResult = !params.pageFound;
+    sp.options.goToFirstResult = !params.pageFound;
 
     // If initialSearchTerm not set
-    if (!this.options.initialSearchTerm) {
+    if (!sp.initialSearchTerm) {
       // Look for any term in URL
       if (params.search) {
         // Old style: /search/[term]
-        this.options.initialSearchTerm = params.search;
-        this.searchTerm = params.search;
+        sp.options.initialSearchTerm = params.search;
+        sp.searchTerm = params.search;
       } else {
         // If we have a query string: q=[term]
         const searchParams = new URLSearchParams(this.readQueryString());
         const searchTerm = searchParams.get('q');
         if (searchTerm) {
-          this.options.initialSearchTerm = utils.decodeURIComponentPlus(searchTerm);
+          sp.options.initialSearchTerm = utils.decodeURIComponentPlus(searchTerm);
         }
       }
     }
@@ -638,7 +660,7 @@ BookReader.prototype.init = function() {
   }
 
   // If not searching, set to allow on-going fragment changes
-  if (!this.options.initialSearchTerm) {
+  if (!this._plugins.search?.options.initialSearchTerm) {
     this.suppressFragmentChange = false;
   }
 
@@ -1052,16 +1074,20 @@ BookReader.prototype._isIndexDisplayed = function(index) {
 BookReader.prototype.jumpToIndex = function(index, pageX, pageY, noAnimate) {
   // Don't jump into specific unviewable page
   const page = this.book.getPage(index);
+
   if (!page.isViewable && page.unviewablesStart != page.index) {
     // If already in unviewable range, jump to end of that range
     const alreadyInPreview = this._isIndexDisplayed(page.unviewablesStart);
-    const newIndex = alreadyInPreview ? page.findNext({ combineConsecutiveUnviewables: true }).index : page.unviewablesStart;
-    return this.jumpToIndex(newIndex, pageX, pageY, noAnimate);
-  }
-
-  this.trigger(BookReader.eventNames.stop);
+    const newIndex = alreadyInPreview ? page.findNext({ combineConsecutiveUnviewables: true })?.index : page.unviewablesStart;
+    // Rare, but a book can end on an unviewable page, so this could be undefined
+    if (typeof newIndex !== 'undefined') {
+      this.jumpToIndex(newIndex, pageX, pageY, noAnimate);
+    }
+  } else {
+    this.trigger(BookReader.eventNames.stop);
 
-  this.activeMode.jumpToIndex(index, pageX, pageY, noAnimate);
+    this.activeMode.jumpToIndex(index, pageX, pageY, noAnimate);
+  }
 };
 
 /**
@@ -1298,7 +1324,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.options.initialSearchTerm && !suppressFragmentChange) {
+  if (this._plugins.search.options.initialSearchTerm && !suppressFragmentChange) {
     this.suppressFragmentChange = false;
   }
 
@@ -1627,8 +1653,8 @@ BookReader.prototype.updateFromParams = function(params) {
   // process /search
   // @deprecated for urlMode 'history'
   // Continues to work for urlMode 'hash'
-  if (this.enableSearch && 'undefined' != typeof(params.search)) {
-    if (this.searchTerm !== params.search) {
+  if (this._plugins.search?.enabled && 'undefined' != typeof(params.search)) {
+    if (this._plugins.search.searchTerm !== params.search) {
       this.$('.BRsearchInput').val(params.search);
     }
   }
@@ -1832,8 +1858,8 @@ BookReader.prototype.paramsFromCurrent = function() {
     params.view = fullscreenView;
   }
   // Search
-  if (this.enableSearch) {
-    params.search = this.searchTerm;
+  if (this._plugins.search?.enabled) {
+    params.search = this._plugins.search.searchTerm;
   }
 
   return params;

package/src/BookReaderPlugin.js

@@ -34,6 +34,14 @@ export class BookReaderPlugin {
   _configurePageContainer(pageContainer) {
   }
 
+  /**
+   * @abstract
+   * @protected
+   * @param {JQuery<HTMLElement>} $toolbarElement
+   */
+  _configureToolbar($toolbarElement) {
+  }
+
   /** @abstract @protected */
   _bindNavigationHandlers() {}