epub-flow 📖

A premium, feature-rich EPUB reader library for Angular applications. Built with performance, aesthetics, and ease of use in mind.

✨ Features

• 📖 Smooth Reading: Powered by Epub.js for reliable rendering.
• 🌓 Aesthetic Dark Mode: Support for modern dark aesthetics with rgb(32 33 32) background.
• 🖋️ Rich Text Notes: Integrated ngx-editor for professionally formatted notes.
• 📚 Beautiful TOC: Hierarchical Table of Contents with smooth navigation.
• 🖼️ Cover Preview: pulse-animated book cover previews during load.
• 🏷️ State-Managed Annotations: Fully event-driven highlights and underlines.
• 📱 Responsive: Mobile-first design that looks great on any device.
• 🔍 Advanced Search: Case-insensitive search with highlighted snippets.
• ⚙️ Customizable: Toggle features like text selection, font sizing, and chapter lists.

🚀 Installation

Install the package via npm:

npm install epub-flow --legacy-peer-deps

Ensure the following peer dependencies are installed:

npm install epubjs ngx-editor @angular/cdk --save

🛠 Setup

1. Import EpubReaderModule

Add EpubReaderModule to your module:

import { EpubReaderModule } from 'epub-flow';


@NgModule({
  imports: [
    EpubReaderModule,
    // ... other imports
  ]
})
export class AppModule { }

2. Include Required Styles

Add the necessary styles to your styles.scss or angular.json:

/* In styles.scss */
@import "ngx-editor/lib/styles/editor.scss";

📖 Usage

Basic Usage

<epub-flow [epubBlob]="myEpubBlob"></epub-flow>

Advanced Usage (Event-Driven)

The component is designed to be stateless regarding annotations, allowing the parent application to manage persistence.

<epub-flow 
  [epubBlob]="bookBlob" 
  [underlineCfiList]="myUnderlines"
  [highlightCfiList]="myHighlights"
  [bookmarkCfiList]="myBookmarks"
  (underlineAddRequest)="onUnderlineAdd($event)"
  (underlineRemoveRequest)="onUnderlineRemove($event)"
  (highlightAddRequest)="onHighlightAdd($event)"
  (highlightRemoveRequest)="onHighlightRemove($event)"
  (bookmarkAddRequest)="onBookmarkAdd($event)"
  (bookmarkRemoveRequest)="onBookmarkRemove($event)">
</epub-flow>

// Example Handler
onHighlightAdd(event: {cfi: string, color: string}) {
  console.log('User added highlight:', event.cfi, 'with color:', event.color);
  // 1. Save to your DB via API
  // 2. Update your local 'myHighlights' array to persist across sessions
}

⚙️ Configuration

Inputs

| Input | Type | Default | Description | |---|---|---|---| | epubBlob | Blob | null | Local Blob object for direct loading. | | coverPage | string | null | URL to a cover image displayed during loading. | | underlineCfiList | string[] | UnderlinePayload[] | [] | List of CFIs (strings) or objects {cfiLocation, colorCode} to be underlined. | | underlineColor | string | null | Default color for underlines (e.g. '#FF0000'). Overrides theme contrast color. | | highlightCfiList | {cfi:string, color:string}[] | [] | List of objects to be rendered as highlights. | | bookmarkCfiList | string[] | [] | List of CFIs to be rendered as bookmarks. | | pagePosition | string | null | The CFI location to navigate to on load or change. | | colourCodeList | string[] | ['#F44336', ...] | List of hex codes for highlight colors. | | underlineColorList | string[] | null | Optional list of colors. If provided, enables color picker for underlines. | | menuConfig | MenuConfig | null | Configuration for custom menu items and quick actions. | | enableDarkMode | boolean | true | Toggle Dark Mode availability. | | enableSearch | boolean | true | Toggle the Search tool. | | enableHighlights | boolean | true | Toggle Underline/Highlighting tools. | | enableBookmarks | boolean | true | Toggle Bookmarking tool. | | enableNotes | boolean | true | Toggle Rich Text note creation. | | enableChapterList | boolean | true | Toggle Chapter List availability. | | enableFontSize | boolean | true | Toggle Font size adjustment controls. | | enableTextSelection | boolean | true | Toggle ability to select text. |

Outputs

| Output | Payload | Description | |---|---|---| | underlineAddRequest | UnderlinePayload | Emits when a user selects text to underline (includes optional color). | | underlineRemoveRequest | {cfi: string} | Emits when a user confirms removal of an underline. | | highlightAddRequest | HighlightPayload | Emits when a user selects a highlight color. | | highlightRemoveRequest | {cfi: string} | Emits when a user confirms removal of a highlight. | | bookmarkAddRequest | BookmarkPayload | Emits when a user adds a bookmark (Capture CFI, Color, Percentage). | | customMenuAction | {id: string, data: any} | Emits when a custom menu item is clicked. | | bookmarkRemoveRequest | BookmarkPayload | Emits when a user removes a bookmark. | | pagePositionOnDestroy | string | Emits the current CFI when the component is destroyed. |

📄 License

MIT