@internetarchive/bookreader 5.0.0-18

package/README.md

@@ -0,0 +1,205 @@
+# Internet Archive BookReader
+
+![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.**
+
+
+<p align="center">
+  <img width="200" src="./BookReaderDemo/assets/v5/Bookreader-logo-lines.svg" alt="Internet Archive BookReader full logo">
+</p>
+
+
+<div style="border: 1px solid gray; padding: 2px; margin-bottom: 20px"><img src="./BookReaderDemo/assets/v5/bookreader-v5-screenshot.png" alt="BookReader v5 interface screenshot"></div>
+
+
+The Internet Archive BookReader is used to view books from the Internet Archive online and can also be used to view other books.
+
+See live examples:
+- On details page: https://archive.org/details/birdbookillustra00reedrich
+- Full window: https://archive.org/details/birdbookillustra00reedrich?view=theater
+- Embedded url for iFrames: https://archive.org/embed/birdbookillustra00reedrich
+
+## Demos
+
+See `BookReaderDemo` directory. These can be tested by building the source files (make sure [Node.js is installed](https://nodejs.org/en/download/)):
+
+```bash
+npm run build
+```
+
+and starting a simple web server in the root directory:
+
+```
+npm run serve
+```
+
+And then open `http://localhost:8000/BookReaderDemo/demo-simple.html`.
+
+
+## Usage
+
+Here is a short example.
+
+```js
+// Create the BookReader object
+var options = {
+  data: [
+    [
+      { width: 800, height: 1200,
+        uri: '//archive.org/download/BookReader/img/page001.jpg' },
+    ],
+    [
+      { width: 800, height: 1200,
+        uri: '//archive.org/download/BookReader/img/page002.jpg' },
+      { width: 800, height: 1200,
+        uri: '//archive.org/download/BookReader/img/page003.jpg' },
+    ],
+    [
+      { width: 800, height: 1200,
+        uri: '//archive.org/download/BookReader/img/page004.jpg' },
+      { width: 800, height: 1200,
+        uri: '//archive.org/download/BookReader/img/page005.jpg' },
+    ]
+  ],
+
+  bookTitle: 'Simple BookReader Presentation',
+
+  // thumbnail is optional, but it is used in the info dialog
+  thumbnail: '//archive.org/download/BookReader/img/page014.jpg',
+
+  // Metadata is optional, but it is used in the info dialog
+  metadata: [
+    {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.'},
+  ],
+
+  ui: 'full', // embed, full (responsive)
+
+};
+var br = new BookReader(options);
+
+// Let's go!
+br.init();
+
+```
+## Architecture Overview
+Starting at v5, BookReader introduces hybrid architecture that merges the core code written in jQuery closer to its evolution as a web component.  As we march toward the future of BookReader as a web component, we are taking an Event Driven approach to connect the two together.
+
+Approach:
+- Event driven
+  - BookReader's (BR) core code emits [custom events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent), reporting the actions it takes:
+    - UI changes
+      - Core Events [src/BookReader/events.js](https://github.com/internetarchive/bookreader/tree/master/src/BookReader/events.js)
+    - API returns
+      - Search API [src/BookReader/events.js](https://github.com/internetarchive/bookreader/tree/master/src/BookReader/events.js)
+  - BookNavigator, BR's web components controller, listens and reacts to these events in order to populate the side menu panels
+- Control BR from the outside by using public methods
+  - When BookNavigator reacts to BR's events, BookNavigator can directly control BR core using public functions.
+    - As we continue to decouple the UI from drawing/calculating logic, these logical methods will become easier to spot, raise as a public method, and create unit tests for them.
+
+### Menu panels: Web Components via LitElement
+BookReader's side navigation is powered by LitElement flavored web components.
+
+
+### Core: jQuery
+BookReader's core functionality is in jQuery.
+This includes:
+- drawing & resizing the book and the various modes (1up, 2 page spread, gallery view)
+- the horizontal navigation
+- search API service
+- plugins
+
+A peek in how to use/extend core functionality:
+- Properties
+  - TODO (for now see [src/BookReader/options.js](https://github.com/internetarchive/bookreader/tree/master/src/BookReader/options.js))
+- Plugins
+  - A basic plugin system is used. See the examples in the plugins directory. The general idea is that they are mixins that augment the BookReader prototype. See the plugins directory for all the included plugins, but here are some examples:
+    - plugin.autoplay.js - autoplay mode. Flips pages at set intervals.
+    - plugin.chapters.js - render chapter markers
+    - plugin.search.js - add search ui, and callbacks
+    - plugin.tts.js - add tts (read aloud) ui, sound library, and callbacks
+    - 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]
+
+### Embedding BookReader in an iFrame
+
+BookReader can be embedded within an `<iframe>`. If you use the IFrame Plugin inside the `<iframe>`, the reader will send notifications about changes in the state of the reader via [`window.postMessage()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). The parent window can send messages of its own (also via `window.postMessage()`) and the IFrame Plugin will handle updating the reader to match.
+
+### Message Events
+
+#### Fragment Change
+The Fragment Change message is sent to the parent window when the embedded BookReader moves between pages/modes. When the `<iframe>` receives this message, it moves to the specified page/mode. The “fragment” is formatted in accordance with the [BookReader URL spec](http://openlibrary.org/dev/docs/bookurls).
+
+```json
+{
+  "type": "bookReaderFragmentChange",
+  "fragment": "page/n1/mode/2up"
+}
+```
+
+## Development
+
+(updates?)
+
+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.
+
+## Releases
+
+To version bump the repo and prepare a release, run `npm version major|minor|patch` (following [semver](https://semver.org/)), then (something like) `git push origin HEAD --tags`. It'll automatically update the version number where it appears, build the files, and ask you to update the CHANGELOG.
+
+We release BookReader [in-repo as tags](https://github.com/internetarchive/bookreader/releases) & also as a node module [@internetarchive/bookreader](https://www.npmjs.com/package/@internetarchive/bookreader)
+
+## Tests
+We would like to get to 100% test coverage and are tracking our progress in this project: [BookReader Fidelity](https://github.com/internetarchive/bookreader/projects/5)
+
+### End to end tests
+We also have end to end tests using [Testcafe](https://devexpress.github.io/testcafe/documentation/getting-started/).  We write tests for the repo itself and also for our use on archive.org. You can read about them in [here](./tests/e2e/README.md). These are relatively easy to do, and a fantastic way of getting introduced to the wonders of BookReader.  Check the project board for open tickets to work on.  And if you don't see a test for something you spotted, feel free to make an issue.
+
+To run all local end to end tests, run command: `npm run test:e2e`
+
+To keep end to end test server on while developing, run command: `npm run test:e2e:dev`
+
+### Unit tests
+We have unit tests and use Jest to run them.
+For mocks, we use Jest's internal mocking mechanism and Sinon to set spies.
+
+To run all local unit tests, run command: `npm run test`
+
+## Ways to contribute
+
+We can always use a hand building BookReader.  Check out the issues and see what interests you.  If you have an idea for an improvement, open an issue.
+
+## More info
+
+Developer documentation:
+https://openlibrary.org/dev/docs/bookreader
+
+Hosted source code:
+https://github.com/internetarchive/bookreader
+
+IIIF (http://iiif.io)
+See `BookReaderDemo/demo-iiif.html` to see an example of how to load an IIIF manifest in BookReader.
+
+
+## Target Devices
+
+Note that BookReader is a core part of Archive.org's mission of Universal Access to All Knowledge. Therefore, care must be taken to support legacy browsers. It should still work and be useable on old devices.
+
+
+## Areas for improvement
+- Change libraries to be NPM dependencies rather than included in the source code
+
+See [CHANGELOG.md](CHANGELOG.md) for history of the project.
+
+
+## License
+The source code license is AGPL v3, as described in the LICENSE file.
+
+## Other credits
+The ability to test on multiple devices is provided courtesy of [Browser Stack](https://www.browserstack.com).

package/babel.config.js

@@ -0,0 +1,18 @@
+module.exports = {
+  presets: [
+    [
+      "@babel/preset-env",
+      {
+        targets: "> 2%, ie 11, edge 14, samsung > 9, OperaMini all, UCAndroid > 12",
+        useBuiltIns: "usage",
+        corejs: 3
+      }
+    ]
+  ],
+  plugins: [
+    ["@babel/plugin-proposal-decorators", {decoratorsBeforeExport: true}],
+    ["@babel/plugin-proposal-class-properties", {loose: true}],
+    ["@babel/plugin-proposal-private-property-in-object", { loose: true }],
+    ["@babel/plugin-proposal-private-methods", { loose: true }]
+  ]
+};

package/codecov.yml

@@ -0,0 +1,17 @@
+codecov:
+  notify:
+    require_ci_to_pass: yes
+
+coverage:
+  precision: 2
+  round: down
+  range: "70...100"
+
+parsers:
+  javascript:
+    enable_partials: yes
+
+ignore:
+  - "BookReader"
+  - "tests"
+

package/index.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>BookReader Demos</title>
+
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
+    <meta name="apple-mobile-web-app-capable" content="yes">
+  </head>
+  <body>
+    <ul>
+      <li><a href="BookReaderDemo/demo-simple.html">Simple</a></li>
+      <li><a href="BookReaderDemo/view_mode.html">Set initial view mode</a></li>
+      <li><a href="BookReaderDemo/toggle_controls.html">Toggle and override individual controls</a></li>
+      <li><a href="BookReaderDemo/demo-fullscreen.html">Fullscreen with mobile nav</a></li>
+      <li><a href="BookReaderDemo/demo-fullscreen-mobile.html">Inline on page, with mobile nav on fullscreen</a></li>
+      <li><a href="BookReaderDemo/demo-vendor-fullscreen.html">Vendor native fullscreen</a></li>
+      <li><a href="BookReaderDemo/demo-advanced.html">Advanced</a></li>
+      <li><a href="BookReaderDemo/demo-preview-pages.html">Preview Pages</a></li>
+      <li><a href="BookReaderDemo/demo-embed.html">Embed</a></li>
+      <li><a href="BookReaderDemo/demo-multiple.html">Multiple on same page</a></li>
+      <li><a href="BookReaderDemo/demo-internetarchive.html?ocaid=theworksofplato01platiala">From Internet Archive</a></li>
+      <li><a href="BookReaderDemo/demo-internetarchive.html?ocaid=adventuresofoli00dick">From Internet Archive - a book with CHAPTERS</a></li>
+      <li><a href="BookReaderDemo/demo-iiif.html">IIIF</a></li>
+      <li><a href="BookReaderDemo/demo-autoplay.html">Autoplay (kiosk mode)</a></li>
+      <li><a href="BookReaderDemo/demo-plugin-menu-toggle.html">Plugin: Full screen menu toggle</a></li>
+      <li><a href="BookReaderDemo/immersion-mode.html">Start in immersion (fullscreen) mode</a></li>
+      <li><a href="BookReaderDemo/immersion-1up.html">Start in immersion mode on 1up default item</a></li>
+      <li><a href="BookReaderDemo/viewmode-cycle.html">Replace view mode buttons with view mode cycler</a></li>
+     </ul>
+  </body>
+</html>

package/jsconfig.json

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

package/karma.conf.js

@@ -0,0 +1,23 @@
+const { createDefaultConfig } = require('@open-wc/testing-karma');
+const merge = require('deepmerge');
+
+module.exports = (config) => {
+  config.set(
+    merge(createDefaultConfig(config), {
+      files: [
+        // runs all files ending with .test in the test folder,
+        // can be overwritten by passing a --grep flag. examples:
+        //
+        // npm run test -- --grep test/foo/bar.test.js
+        // npm run test -- --grep test/bar/*
+        { pattern: config.grep ? config.grep : 'tests/karma/**/*.test.js', type: 'module' },
+      ],
+
+      esm: {
+        nodeResolve: true,
+      },
+      // you can overwrite/extend the config further
+    }),
+  );
+  return config;
+};

package/package.json

@@ -0,0 +1,129 @@
+{
+  "name": "@internetarchive/bookreader",
+  "version": "5.0.0-18",
+  "description": "The Internet Archive BookReader.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/internetarchive/bookreader.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "module": "src/BookNavigator/BookNavigator.js",
+  "keywords": [
+    "online",
+    "bookreader",
+    "interface",
+    "ebooks",
+    "internet archive"
+  ],
+  "author": "Internet Archive",
+  "license": "AGPL-3.0",
+  "bugs": {
+    "url": "https://github.com/internetarchive/bookreader/issues"
+  },
+  "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.1.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.15.0",
+    "@babel/plugin-proposal-class-properties": "^7.14.5",
+    "@babel/plugin-proposal-decorators": "^7.14.5",
+    "@babel/preset-env": "7.15.0",
+    "@open-wc/testing": "^2.5.33",
+    "@open-wc/testing-karma": "^4.0.9",
+    "@types/jest": "27.0.1",
+    "babel-eslint": "^10.1.0",
+    "babel-loader": "8.2.2",
+    "codecov": "3.8.3",
+    "concurrently": "6.0.2",
+    "core-js": "3.16.2",
+    "cpx2": "3.0.0",
+    "eslint": "^7.32.0",
+    "eslint-plugin-no-jquery": "^2.6.0",
+    "eslint-plugin-testcafe": "0.2.1",
+    "hammerjs": "^2.0.8",
+    "http-server": "0.12.3",
+    "iso-language-codes": "1.1.0",
+    "jest": "27.0.6",
+    "jquery": "1.11.3",
+    "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.9",
+    "sass": "1.38.2",
+    "sinon": "11.1.2",
+    "soundmanager2": "2.97.20170602",
+    "svgo": "2.4.0",
+    "testcafe": "1.15.3",
+    "webpack": "5.51.1",
+    "webpack-cli": "4.8.0"
+  },
+  "jest": {
+    "testEnvironment": "jsdom",
+    "transformIgnorePatterns": [
+      "node_modules/(?!(lit-html|lit-element|lit)/)"
+    ],
+    "setupFiles": [
+      "./src/jquery-wrapper.js"
+    ],
+    "roots": [
+      "<rootDir>/src/",
+      "<rootDir>/tests/"
+    ],
+    "testPathIgnorePatterns": [
+      "<rootDir>/tests/e2e/",
+      "<rootDir>/tests/karma/"
+    ],
+    "coverageDirectory": "<rootDir>/coverage-jest"
+  },
+  "scripts": {
+    "preversion": "npm run test && 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-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-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",
+    "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",
+    "DOCS:update:test-deps": "If CI succeeds, these should be good to update",
+    "update:test-deps": "npm i @open-wc/testing@latest @open-wc/testing-karma@latest @types/jest@latest babel-eslint@latest codecov@latest eslint@latest eslint-plugin-testcafe@latest jest@latest karma-coverage@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-loader@latest core-js@latest regenerator-runtime@latest sass@latest svgo@latest webpack@latest webpack-cli@latest",
+    "codecov": "npx codecov"
+  }
+}

package/scripts/postversion.js

@@ -0,0 +1,10 @@
+const fs = require('fs');
+const { version: NEW_VERSION } = require('../package.json');
+
+const tag = `v${NEW_VERSION}`;
+const releaseBody = fs.readFileSync('CHANGELOG.md').toString()
+.split(/\n# /)[0] // split at headings and get first heading
+.split('\n').slice(1).join('\n'); // remove heading line
+
+const GITHUB_RELEASE_URL = `https://github.com/internetarchive/bookreader/releases/new?tag=${tag}&title=${tag}&body=${encodeURIComponent(releaseBody)}`;
+console.log(`After you push/merge, use this link to release: ${GITHUB_RELEASE_URL}`);

package/scripts/preversion.js

@@ -0,0 +1,14 @@
+const { version: OLD_VERSION } = require('../package.json');
+const fetch = require('node-fetch');
+const OLD_RELEASE_URL = `https://api.github.com/repos/internetarchive/bookreader/releases/tags/v${OLD_VERSION}`;
+
+async function main() {
+    const {created_at} = await fetch(OLD_RELEASE_URL).then(r => r.json());
+    const today = new Date().toISOString().slice(0, -5);
+    const searchUrl = 'https://github.com/internetarchive/bookreader/pulls?' + new URLSearchParams({
+        q: `is:pr is:merged merged:${created_at}..${today}Z sort:updated-asc`
+    }).toString();
+    console.log(`Here are all the PRs that were merged since the last version: ${searchUrl}`);
+}
+
+main();

package/scripts/version.js

@@ -0,0 +1,26 @@
+const fs = require('fs');
+const { execSync } = require('child_process');
+const { version: NEW_VERSION } = require('../package.json');
+
+async function main() {
+    // Update the changelog
+    const old_changelog = fs.readFileSync('CHANGELOG.md').toString();
+    const new_changelog = `# ${NEW_VERSION}\n<!-- Write here... -->\n\n` + old_changelog;
+    fs.writeFileSync('CHANGELOG.md', new_changelog);
+    while (fs.readFileSync('CHANGELOG.md').toString().includes('<!-- Write here... -->')) {
+        console.log('Changelog contains dummy text. Update the changelog, and press ENTER continue.');
+        await new Promise(res => process.stdin.once("data", res));
+    }
+    execSync('git add CHANGELOG.md');
+
+    // npm install to make sure deps are correct
+    execSync('npm install', { stdio: "inherit" });
+
+    // build
+    execSync('npm run build', { stdio: "inherit" });
+
+    // Add build files
+    execSync('git add ./BookReader');
+}
+
+main().then(() => process.exit());

package/src/BookNavigator/BookModel.js

@@ -0,0 +1,14 @@
+export class Book {
+  constructor() {
+    this.metadata = {};
+    this.isRestricted = null;
+  }
+
+  setMetadata(itemMetadata) {
+    this.metadata = itemMetadata;
+  }
+
+  setRestriction(isRestricted) {
+    this.isRestricted = isRestricted;
+  }
+}