@treinetic/treinetic-epub-reader 1.3.1 → 2.0.0

package/README.md

@@ -1,191 +1,162 @@
-# Treinetic-epub-reader
+# Treinetic Epub Reader 2.0.0
 
-Treinetic-epub-reader is a fork of popular [readium-js-viewer](https://raw.githubusercontent.com/readium/readium-js-viewer) but customized and simplified the usage of the library 
+A modern, lightweight, and framework-agnostic EPUB reader for the web, built with TypeScript.
+This project is an initiative of Treinetic (Pvt) Ltd, Sri Lanka.
 
-<img src="https://drive.google.com/uc?export=view&id=1kl3sKt0mxyjm_2YAmAV4PXaHT2XhAnBq" width="100%" />
+![Issues](https://img.shields.io/github/issues/Treinetic/TreineticEpubReader.svg?style=flat-square)
+[![Software License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
+![Forks](https://img.shields.io/github/forks/Treinetic/TreineticEpubReader.svg?style=flat-square)
+![Stars](https://img.shields.io/github/stars/Treinetic/TreineticEpubReader.svg?style=flat-square)
+![Twitter](https://img.shields.io/twitter/url/https/github.com/Treinetic/TreineticEpubReader.svg?style=social)
 
-## Usage
-
-1. Install the library
-
-    ```bash 
-        npm install @treinetic/treinetic-epub-reader --save
-    ```
-    
-2. refer `css` and `js` lib in your html ( jquery is a must )
-
-```html
-<script src="https://code.jquery.com/jquery-3.4.1.min.js"></script>
-<link rel="stylesheet" type="text/css" href="../node_modules/@treinetic/treinetic-epub-reader/dist/TreineticEpubReader.min.css">
-<script type="text/javascript" src="../node_modules/@treinetic/treinetic-epub-reader/dist/TreineticEpubReader.min.js"></script>
-```
-
-3. create placeholder divs for the reader.
+This library allows you to easily embed an EPUB reader into any web application. It handles parsing, rendering, pagination, and navigation, while leaving the UI (buttons, sidebars, menus) completely up to you.
 
-```html
-<div id="epub-reader-frame"></div>
-```
-
-4. Javascript 
-```javascript
-
-//Register the reader events and get reader controller object ( note that these are just callbacks you can't treat them as events though )
-
-var exControls = TreineticEpubReader.handler();
-exControls.registerEvent("onEpubLoadSuccess", function () {
-
-});
+---
 
-exControls.registerEvent("onEpubLoadFail", function () {
+## Features
 
-});
+| Feature | Description |
+| :--- | :--- |
+| **Framework Agnostic** | Works seamlessly with React, Vue, Angular, or Vanilla JS. |
+| **Lightweight** | Zero heavy dependencies. Uses native Iframe isolation for security and style encapsulation. |
+| **Fully Responsive** | **New:** Automatically adapts padding and font sizes using internal container logic (Internal Wrapper Pattern). |
+| **Themable** | Inject custom CSS, change fonts, and toggle dark mode easily. |
+| **TypeScript** | Fully typed for a great developer experience. |
+| **Modern Build** | ESM and UMD support via Vite for modern bundlers. |
+| **Continuous Scroll** | Support for both Paginated (Kindle-style) and Vertical Scrolling modes. |
 
-exControls.registerEvent("onTOCLoaded", function (hasTOC) {
-    if (!hasTOC) {
-       let toc =  exControls.getTOCJson();
-    }
-    // you can use following api calls after this
-    /**
-    exControls.hasNextPage()
-    exControls.nextPage();
-    exControls.hasPrevPage()
-    exControls.prevPage();
-    exControls.makeBookMark();
-    exControls.changeFontSize(int);
-    exControls.changeColumnMaxWidth(int);
-    exControls.setTheme("theme-id-goes-here");
-    exControls.setScrollMode("scroll-type-id-goes-here");
-    exControls.setDisplayFormat("display-format-id-goes-here");
-
-    extcontrols.getRecommendedFontSizeRange()
-    extcontrols.getRecommendedColumnWidthRange()
-    var list = extcontrols.getAvailableThemes();
-    var list = extcontrols.getAvailableScrollModes();
-    var list = extcontrols.getAvailableDisplayFormats();
-    var settings = extcontrols.getCurrentReaderSettings();
-    **/
-});
+## Requirements
 
+-   NodeJS 16+ (for development)
+-   Modern Browser (ES6 Support)
 
-// You can feed epub file as well as extracted path of the epub 
-// if you are planning to use epub file directly make sure that worker js files inside `ZIPJS` the `dist` is copied outside to a accessible location.
-// and set the root folder path of those files to 'jsLibRoot'  
-var config = TreineticEpubReader.config();
-config.jsLibRoot = "src/ZIPJS/";
+## Installation
 
-TreineticEpubReader.create("#epub-reader-frame");
-TreineticEpubReader.open("assets/epub/epub_1.epub");
+### 1. NPM
+Install the package via npm:
 
-To see a code sample open `sample` folder inside the `dist`
+```bash
+npm install @treinetic/treinetic-epub-reader
 ```
 
-## License
-
-**BSD-3-Clause** ( http://opensource.org/licenses/BSD-3-Clause )
-
-See [license.txt](./license.txt).
-
-
-## Development
-
-### Git initialisation
-
-* `git clone --recursive -b BRANCH_NAME https://github.com/Treinetic/TreineticEpubReader.git TreineticEpubReader` (replace "BRANCH_NAME" with e.g. "development")
-* `cd TreineticEpubReader`
-* `git submodule update --init --recursive` to ensure that the TreineticEpubReader chain of dependencies is initialised (readium-js, readium-shared-js)
-* `git checkout BRANCH_NAME && git submodule foreach --recursive "git checkout BRANCH_NAME"` (or simply `cd` inside each repository / submodule, and manually enter the desired branch name: `git checkout BRANCH_NAME`) Git should automatically track the corresponding branch in the 'origin' remote.
-
-
-Advanced usage (e.g. TravisCI) - the commands below automate the remote/origin tracking process (this requires a Bash-like shell):
-
-* ``for remote in `git branch -r | grep -v \> | grep -v master`; do git branch --track ${remote#origin/} $remote; done`` to ensure that all Git 'origin' remotes are tracked by local branches.
-* ``git checkout `git for-each-ref --format="%(refname:short) %(objectname)" 'refs/heads/' | grep $(git rev-parse HEAD) | cut -d " " -f 1` `` to ensure that Git checks-out actual branch names (as by default Git initializes submodules to match their registered Git SHA1 commit, but in detached HEAD state)
-
-(repeat for each repository / submodule)
+### 2. Manual
+Alternatively, you can include the `dist/treinetic-epub-reader.umd.js` and `dist/style.css` manually in your project.
 
+## Running the Demo
 
-### Source tree preparation
+To see the reader in action with a sample UI:
 
-* `npm run prepare:all` (to perform required preliminary tasks, like patching code before building)
- * OR: `yarn run prepare:yarn:all` (to use Yarn instead of NPM for node_module management)
-
-Note that in some cases, administrator rights may be needed in order to install dependencies, because of NPM-related file access permissions (the console log would clearly show the error). Should this be the case, running `sudo npm run prepare:all` usually solves this.
-
-Note that the above command executes the following:
-
-* `npm install` (to download dependencies defined in `package.json` ... note that the `--production` option can be used to avoid downloading development dependencies, for example when testing only the pre-built `build-output` folder contents)
-* `npm update` (to make sure that the dependency tree is up to date)
-* + some additional HTTP requests to the GitHub API in order to check for upstream library updates (wherever Readium uses a forked codebase)
-
-
-### Typical workflow
-
-No RequireJS optimization:
-
-* `npm run http` (to launch an http server. This automatically opens a web browser instance to the HTML files in the `dev` folder, choose `dev-sample.html` which do include only the reader view)
-* Hack away! (e.g. source code in the `src/js` folder)
-* Press F5 (refresh / reload) in the web browser
-
-Or to use optimized Javascript bundles (single or multiple):
-
-* `npm run build` (to update the RequireJS bundles in the build output folder)
-* `npm run http:watch` (to launch an http server. This automatically opens a web browser instance to the HTML files in the `dev` folder, choose `index_RequireJS_single-bundle.html` or `index_RequireJS_multiple-bundles.html`, or the `*LITE.html` variants which do include only the reader view, not the ebook library view)
-* `npm run http` (same as above, but without watching for file changes (no automatic rebuild))
-
-And finally to update the distribution package.
-
-* `npm run dist` 
-
-Also note that the built-in local HTTP server functionality (`npm run http`) is primarily designed to serve the Readium application at development time in its "exploded" form (`dev`, `src`, `node_modules`, etc. folders). It is also possible to use any arbitrary HTTP server as long as the root folder is `readium-js-viewer` (so that the application assets ; CSS, images, fonts ; can be loaded relative to this base URL). Example with the built-in NodeJS server: `node node_modules/http-server/bin/http-server -a 127.0.0.1 -p 8080 -c-1 .`. Also note that the `127.0.0.1` IP address which is used by default when invoking the `npm run http` command can be set to `0.0.0.0` in order to automatically bind the HTTP server to the local LAN IP, making it possible to open the Readium app in a web browser from another machine on the network. Simply set the `RJS_HTTP_IP` environment variable to `0.0.0.0` (e.g. using `export RJS_HTTP_IP="0.0.0.0"` from the command line), or for a less permanent setting: `RJS_HTTP_IP="0.0.0.0" npm run http` (the environment variable only "lasts" for the lifespan of the NPM command).
-
-Remark: a log of HTTP requests is preserved in `http_app-ebooks.log`. This file contains ANSI color escape codes, so although it can be read using a regular text editor, it can be rendered in its original format using the shell command: `cat http_app.log` (on OSX / Linux), or `sed "s,x,x,g" http_app-ebooks.log` (on Windows).
-
-
-### HTTP CORS (separate domains / origins, app vs. ebooks)
-
-By default, a single HTTP server is launched when using the `npm run http` task, or its "watch" and "nowatch" variants (usage described in the above "Typical workflow" section).
-To launch separate local HTTP servers on two different domains (in order to test HTTP CORS cross-origin app vs. ebooks deployment architecture), simply invoke the equivalent tasks named with `http2` instead of `http`. For example: `npm run http2`. More information about real-world HTTP CORS is given in the "Cloud reader deployment" section below.
-
-Remark: logs of HTTP requests are preserved in two separate files `http_app.log` and `http_ebooks.log`. They contains ANSI color escape codes, so although they can be read using a regular text editor, they can be rendered in their original format using the shell command: `cat http_app.log` (on OSX / Linux), or `sed "s,x,x,g" http_app.log` (on Windows).
+```bash
+git clone https://github.com/Treinetic/TreineticEpubReader.git
+cd TreineticEpubReader
+npm install
+npm run demo
+```
+This will start a local server at `http://localhost:3001` with hot-reloading.
 
+## Usage
 
-### Forking
+### Basic Usage
 
-Assuming a fork of `https://github.com/Treinetic/TreineticEpubReader` is made under `USER` at `https://github.com/USER/TreineticEpubReader`, the `.gitmodules` file ( https://github.com/Treinetic/readium-js-viewer/blob/develop/.gitmodules ) will still point to the original submodule URL (at `Treinetic`, instead of `USER`). Thankfully, one can simply modify the `.gitmodules` file by replacing `https://github.com/Treinetic/` with `https://github.com/USER/`, and do this for every submodule (`readium-js-viewer` > `readium-js` > `readium-shared-js`). Then the Git command `git submodule sync` can be invoked, for each submodule.
+First, import the necessary classes and CSS.
 
+```typescript
+import TreineticEpubReader from '@treinetic/treinetic-epub-reader';
+import '@treinetic/treinetic-epub-reader/dist/style.css'; 
 
-### Plugins integration
+// Create the reader instance targeting your container
+const reader = TreineticEpubReader.create("#epub-reader-frame");
 
-When invoking the `npm run build` command, the generated `build-output` folder contains RequireJS module bundles that include the default plugins specified in `readium-js/readium-js-shared/plugins/plugins.cson` (see the plugins documentation https://github.com/readium/readium-shared-js/blob/develop/PLUGINS.md ). Developers can override the default plugins configuration by using an additional file called `plugins-override.cson`. This file is git-ignored (not persistent in the Git repository), which means that Readium's default plugins configuration is never at risk of being mistakenly overridden by developers, whilst giving developers the possibility of creating custom builds on their local machines.
+// Load an EPUB file (url or base64)
+reader.open("path/to/book.epub");
+```
 
-For example, the `annotations` plugin can be activated by adding it to the `include` section in `readium-js/readium-js-shared/plugins/plugins-override.cson`.
-Then, in order to create / remove highlighted selections, simply comment `display:none` for `.icon-annotations` in the `src/css/viewer.css` file (this will enable an additional toolbar button).
+### HTML Structure
+Create a container for the reader. The library will inject an internal wrapper and iframe into this div.
 
+```html
+<div id="epub-reader-frame" style="width: 100%; height: 600px;"></div>
+```
+> [!TIP]
+> You can resize this container at will. The reader monitors its own size and adjusts layouts (padding, columns) automatically.
 
-## RequireJS bundle optimisation
+### Controlling the Reader
 
-Note that by default, compiled RequireJS bundles are minified / mangled / uglify-ed. You can force the build process to generate non-compressed Javascript bundles by setting the `RJS_UGLY` environment variable to "no" or "false" (any other value means "yes" / "true").
+```typescript
+// Navigation
+document.getElementById('next-btn').onclick = () => reader.nextPage();
+document.getElementById('prev-btn').onclick = () => reader.prevPage();
 
-This may come-in handy when testing / debugging the Chrome Extension (Packaged App) in "developer mode" directly from the `dist` folder (i.e. without the sourcemaps manually copied into the script folder).
+// Settings
+reader.setTheme('night'); // 'day', 'night', 'sepia'
+reader.setFontSize(120);  // Percentage
+```
 
-## Tests
+### API Reference
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| `open` | `(url: string) => void` | Loads and renders an EPUB file. |
+| `nextPage` | `() => void` | Navigates to the next page or chapter. |
+| `prevPage` | `() => void` | Navigates to the previous page or chapter. |
+| `goToPage` | `(href: string) => void` | Navigates to a specific spine item (chapter). |
+| `getTOC` | `() => TOCItem[]` | Returns the Table of Contents as a JSON tree. |
+| `setTheme` | `(id: string) => void` | Switches themes (e.g. 'night', 'sepia', 'day'). |
+| `registerTheme` | `(theme: ReaderTheme) => void` | Registers a new custom theme. |
+| `setFontSize` | `(size: number) => void` | Sets font size (percentage, e.g. 120). |
+| `setScrollOption`| `(mode: 'auto' \| 'scroll-continuous')` | Toggle between Paginated and Vertical Scroll. |
+| `clearSettings` | `() => void` | Resets all user preferences (font, theme, location). |
+
+### Keyboard Shortcuts
+| Key | Action |
+| :--- | :--- |
+| `ArrowRight` | Next Page |
+| `ArrowLeft` | Prev Page |
+
+## 🎨 Advanced Customization
+
+### Creating Custom Themes
+You are not limited to the default themes. You can register your own:
+
+```typescript
+reader.registerTheme({
+    id: 'matrix-theme',
+    name: 'Matrix Mode',
+    style: {
+        'body': {
+            'background-color': '#000000',
+            'color': '#00FF00'
+        },
+        'p': {
+            'font-family': 'monospace'
+        }
+    }
+});
 
-Mocha-driven UI tests via Selenium (not PhantomJS, but actual installed browsers accessed via WebDriver):
+reader.setTheme('matrix-theme');
+```
 
-* `npm run test:firefox`
-* `npm run test:chrome`
-* `npm run test:chromeApp`
+## 🗺️ Project Roadmap
+We have an ambitious vision to make this the de facto standard for open-source EPUB rendering.
+Please see our detailed [ROADMAP](roadmap.md) for upcoming features like Full-Text Search, Offline support, and Mobile gestures.
 
-`npm run test` (runs all of the above)
+## Project Structure
 
-PS: you may need to install the Chrome WebDriver from https://sites.google.com/a/chromium.org/chromedriver/downloads
+This project has been modernized (v2.0.0) to separate the **Core Library** from the **Demo Application**.
 
-Via SauceLabs:
+*   `src/lib/`: **The Library**. Contains the core logic (`TreineticEpubReader.ts`, `ReaderView.ts`).
+*   `src/css/`: **Library CSS**. `main.css` (layout) and `responsive.css` (adaptive padding).
+*   `demo/`: **The Demo App**. Contains the UI (`index.html`, `demo.css`, `demo.js`).
+*   `dist/`: **Build Output**. The compiled files published to NPM.
 
-* `npm run test:sauce:firefox`
-* `npm run test:sauce:chrome`
-* `npm run test:sauce:chromeApp`
+## Contributing
+Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
 
-`npm run test:sauce` (runs all of the above)
+## Credits
+-   [Imal Hasaranga Perera](https://github.com/imalhasaranga)
+-   [Nuril Ahemad](https://github.com/nurilahemad)
+-   [All Contributors](../../contributors)
 
-Travis (Continuous Integration) automatically uses a chromeApp and Firefox test matrix (2x modes), and uses SauceLabs to actually run the test. See https://travis-ci.org/readium/readium-js-viewer/
+## License
+The MIT License (MIT). Please see [License File](LICENSE) for more information.
+(Portions based on the original ReadiumJS viewer, BSD-3-Clause).

package/dist/style.css

@@ -0,0 +1 @@
+#epub-reader-frame{display:block;height:100%;width:100%;position:relative;border:none;box-sizing:border-box}.tr-epub-reader-element{container-type:inline-size;width:100%;height:100%;position:relative;padding:0;scrollbar-width:none;-ms-overflow-style:none}.tr-internal-wrapper{display:grid;width:100%;min-height:100%;box-sizing:border-box;padding:20px}.tr-epub-reader-element::-webkit-scrollbar{display:none}@container (max-width: 800px){.tr-internal-wrapper{padding:14px!important}}@container (max-width: 500px){.tr-internal-wrapper{padding:5px!important}}