flipbookengine 0.5.3 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +42 -30
- package/COMMERCIAL_LICENSE.md +45 -45
- package/LICENSE +661 -661
- package/README.md +257 -252
- package/THIRD-PARTY-NOTICES.md +117 -117
- package/TRADEMARK_POLICY.md +50 -50
- package/dist/adapters/PageFlipAdapter.d.ts +1 -0
- package/dist/components/TableOfContents.d.ts +8 -0
- package/dist/components/Toolbar.d.ts +1 -0
- package/dist/core/LayoutManager.d.ts +3 -1
- package/dist/{engine-BuVkDIh-.js → engine-MdZzt6R9.js} +899 -803
- package/dist/engine-MdZzt6R9.js.map +1 -0
- package/dist/engine.d.ts +10 -1
- package/dist/flipbook-engine.css +1 -1
- package/dist/flipbook-engine.iife.js +34 -34
- package/dist/flipbook-engine.iife.js.map +1 -1
- package/dist/flipbook-engine.js +5 -4
- package/dist/flipbook-engine.react.js +1 -1
- package/dist/flipbook-engine.react.js.map +1 -1
- package/dist/flipbook-engine.vue.js +1 -1
- package/dist/flipbook-engine.vue.js.map +1 -1
- package/dist/i18n/locales/en.d.ts +1 -0
- package/dist/i18n/locales/tr.d.ts +1 -0
- package/dist/i18n/service.d.ts +3 -0
- package/dist/index.d.ts +3 -1
- package/dist/model/toc.d.ts +13 -0
- package/dist/state/store.d.ts +6 -2
- package/package.json +1 -1
- package/react/package.json +5 -5
- package/vue/package.json +5 -5
- package/dist/engine-BuVkDIh-.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,242 +1,247 @@
|
|
|
1
|
-
# FlipbookEngine
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
[](https://www.npmjs.com/package/flipbookengine)
|
|
7
|
+
[](https://github.com/Bizeka/flipbook-engine/blob/main/LICENSE)
|
|
8
|
+
[](https://www.npmjs.com/package/flipbookengine)
|
|
9
|
+
[](https://www.npmjs.com/package/flipbookengine)
|
|
10
|
+
|
|
11
|
+
**[Live Demo & Playground ↗](https://flipbookengine.com)**
|
|
12
|
+
|
|
13
|
+
FlipbookEngine is a modern, lightweight, and embeddable HTML flipbook viewer for PDF-backed catalogs, brochures, and digital publications. Written in TypeScript, it features single-page and spread modes, a thumbnail rail, smooth zoom/pan, full internationalization (i18n), and robust theme customization.
|
|
14
|
+
|
|
15
|
+
## Highlights
|
|
16
|
+
|
|
17
|
+
- **Dual-Mode Layout**: Seamlessly switches between single-page (mobile-optimized) and spread (book/catalog layout) modes.
|
|
18
|
+
- **Rich Interaction**: Built-in thumbnail navigation rail, smooth zoom & pan, and HTML5 fullscreen support.
|
|
19
|
+
- **Media & Autoplay**: Configurable page-flip sound effects and automated slideshow presentation with `Autoplay`.
|
|
20
|
+
- **Theme Engine**: Styled with compiled CSS and CSS Custom Properties, featuring full support for light/dark modes (auto-responsive to Bootstrap 5 or tailorable per instance).
|
|
21
|
+
- **Multi-Language (i18n)**: Out-of-the-box support for English (`en`) and Turkish (`tr`) with customizable overrides.
|
|
22
|
+
- **Framework Wrappers**: Direct React and Vue wrapper exports for seamless modern integration.
|
|
23
|
+
- **Progressive PDF Rendering**: PDF pages render on demand with bounded concurrency and an instance-local LRU cache, keeping large documents responsive.
|
|
24
|
+
|
|
25
|
+
## Installation
|
|
26
|
+
|
|
27
|
+
Install via npm:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm install flipbookengine
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`pdfjs-dist` is a production dependency of FlipbookEngine. It is installed by npm, but is deliberately excluded from the FlipbookEngine bundle so applications can deduplicate, cache, and upgrade PDF.js independently.
|
|
34
|
+
|
|
35
|
+
## Quick Start
|
|
36
|
+
|
|
37
|
+
### npm and Bundlers
|
|
38
|
+
|
|
39
|
+
Configure the PDF.js worker in the consuming application. The `?url` suffix is supported by Vite and other modern bundlers that emit imported assets.
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { FlipbookEngine } from 'flipbookengine';
|
|
43
|
+
import 'flipbookengine/styles.css';
|
|
44
|
+
import pdfWorkerSrc from 'pdfjs-dist/build/pdf.worker.mjs?url';
|
|
45
|
+
|
|
46
|
+
const engine = new FlipbookEngine('#viewer', {
|
|
47
|
+
allowDownload: true,
|
|
48
|
+
showThumbs: true,
|
|
49
|
+
primaryColor: '#7367f0',
|
|
50
|
+
theme: 'auto',
|
|
51
|
+
locale: 'en',
|
|
52
|
+
pdfWorkerSrc,
|
|
53
|
+
pdfRenderCacheSize: 32
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
await engine.init('/files/catalog.pdf');
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Passing `pages` remains optional. When omitted, FlipbookEngine creates the page structure from `pdfUrl`, renders the first page before `init` resolves, and prefetches the next page. Additional pages render as they become visible or are selected.
|
|
60
|
+
|
|
61
|
+
`pdfRenderCacheSize` controls the per-instance LRU cache (default `32`, set to `0` to disable it).
|
|
62
|
+
|
|
63
|
+
### Browser CDN
|
|
64
|
+
|
|
65
|
+
Use the ESM build with an import map for PDF.js. The worker must be served from a URL your site permits in its Content Security Policy.
|
|
66
|
+
|
|
67
|
+
```html
|
|
68
|
+
<link rel="stylesheet" href="https://unpkg.com/flipbookengine@0.5.4/dist/flipbook-engine.css" />
|
|
69
|
+
<div id="viewer" style="width: 100%; height: 600px;"></div>
|
|
70
|
+
|
|
71
|
+
<script type="importmap">
|
|
72
|
+
{
|
|
73
|
+
"imports": {
|
|
74
|
+
"pdfjs-dist": "https://unpkg.com/pdfjs-dist@5.4.530/build/pdf.min.mjs"
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
</script>
|
|
78
|
+
<script type="module">
|
|
79
|
+
import { FlipbookEngine } from 'https://unpkg.com/flipbookengine@0.5.4/dist/flipbook-engine.js';
|
|
80
|
+
|
|
81
|
+
const engine = new FlipbookEngine('#viewer', {
|
|
82
|
+
pdfWorkerSrc: 'https://unpkg.com/pdfjs-dist@5.4.530/build/pdf.worker.min.mjs'
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
await engine.init('/files/catalog.pdf');
|
|
86
|
+
</script>
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### React
|
|
90
|
+
|
|
91
|
+
```tsx
|
|
92
|
+
import React, { useRef } from 'react';
|
|
93
|
+
import { Flipbook, FlipbookRef } from 'flipbookengine/react';
|
|
94
|
+
import 'flipbookengine/styles.css';
|
|
95
|
+
|
|
96
|
+
function CatalogViewer() {
|
|
97
|
+
const flipbookRef = useRef<FlipbookRef>(null);
|
|
98
|
+
|
|
99
|
+
const handleNextPage = () => {
|
|
100
|
+
flipbookRef.current?.goToPage(flipbookRef.current.getCurrentPage() + 1);
|
|
101
|
+
};
|
|
102
|
+
|
|
103
|
+
return (
|
|
104
|
+
<Flipbook
|
|
105
|
+
ref={flipbookRef}
|
|
106
|
+
pdfUrl="/files/catalog.pdf"
|
|
107
|
+
pages={[
|
|
108
|
+
{ kind: 'cover', pageNumber: 1, normal: '/img/1.jpg', low: '/img/1-low.jpg', thumb: '/img/1-thumb.jpg' },
|
|
109
|
+
{ kind: 'spread', pageNumbers: [2, 3], normal: '/img/2-3.jpg', low: '/img/2-3-low.jpg', thumb: '/img/2-3-thumb.jpg' }
|
|
110
|
+
]}
|
|
111
|
+
allowDownload={true}
|
|
112
|
+
showThumbs={true}
|
|
113
|
+
primaryColor="#7367f0"
|
|
114
|
+
/>
|
|
115
|
+
);
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Vue 3
|
|
120
|
+
|
|
121
|
+
```vue
|
|
122
|
+
<template>
|
|
123
|
+
<Flipbook
|
|
124
|
+
pdfUrl="/files/catalog.pdf"
|
|
125
|
+
:pages="pages"
|
|
126
|
+
:allowDownload="true"
|
|
127
|
+
:showThumbs="true"
|
|
128
|
+
primaryColor="#7367f0"
|
|
129
|
+
/>
|
|
130
|
+
</template>
|
|
131
|
+
|
|
132
|
+
<script setup>
|
|
133
|
+
import { Flipbook } from 'flipbookengine/vue';
|
|
134
|
+
import 'flipbookengine/styles.css';
|
|
135
|
+
|
|
136
|
+
const pages = [
|
|
137
|
+
{ kind: 'cover', pageNumber: 1, normal: '/img/1.jpg', low: '/img/1-low.jpg', thumb: '/img/1-thumb.jpg' },
|
|
138
|
+
{ kind: 'spread', pageNumbers: [2, 3], normal: '/img/2-3.jpg', low: '/img/2-3-low.jpg', thumb: '/img/2-3-thumb.jpg' }
|
|
139
|
+
];
|
|
140
|
+
</script>
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
## Migration Notes
|
|
144
|
+
|
|
145
|
+
Upgrading from 0.3.x to 0.4.0 keeps the public engine methods intact. The release isolates state per engine instance, makes wrapper updates lifecycle-safe, and scopes viewer markup to its container. If host CSS or automation selected the former fixed viewer IDs, migrate those selectors to the instance classes documented in the theming guide. PDF-backed consumers should configure `pdfWorkerSrc`; image-only viewers do not expose a download control.
|
|
146
|
+
|
|
147
|
+
For 0.5.0 behavior, see the [0.5.0 migration guide](./docs/migration-0.5.0.md). PDF-backed viewers now render on demand; callers should use `progress` and `error` events for rendering telemetry.
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
## Public API Reference
|
|
151
|
+
|
|
152
|
+
The `FlipbookEngine` class exposes the following public methods:
|
|
153
|
+
|
|
154
|
+
- **`init(pdfUrl: string, imageList?: FlipbookPageAsset[])`**: Initializes the viewer and loads the flipbook with pages.
|
|
155
|
+
- **`goToPage(pageIndex: number)`**: Navigates programmatically to a 0-based page index.
|
|
156
|
+
- **`getCurrentPage()`**: Returns the 0-based index of the currently active page.
|
|
157
|
+
- **`getTotalPages()`**: Returns the total number of pages.
|
|
158
|
+
- **`getZoom()`**: Returns the current zoom level (default is `1`).
|
|
159
|
+
- **`setZoom(zoomLevel: number)`**: Programmatically sets the zoom level (accepts values between `0.5` and `5`).
|
|
160
|
+
- **`setSingleMode(isSingle: boolean)`**: Programmatically toggles between single-page mode (`true`) and double-page spread mode (`false`).
|
|
161
|
+
- **`toggleFullscreen()`**: Programmatically toggles fullscreen mode.
|
|
162
|
+
- **`updateOptions(options: Partial<FlipbookEngineOptions>)`**: Updates instance options at runtime.
|
|
163
|
+
- **`setLocale(locale: string, messages?: PartialFlipbookMessages | Record<string, PartialFlipbookMessages>)`**: Updates the locale programmatically and optionally overrides messages for that locale.
|
|
164
|
+
- **`destroy(keepContainer = false)`**: Tears down the instance and listeners; when `true`, keeps the container markup for an immediate reinitialization.
|
|
165
|
+
|
|
166
|
+
### Subscribing to Events
|
|
167
|
+
|
|
168
|
+
You can subscribe to events using `.on()`. PDF-backed initialization reports loading/rendering progress and emits a structured `error` event when loading or rendering fails:
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
const unsubscribe = engine.on('pageChange', ({ currentPage, totalPages, isSingle }) => {
|
|
172
|
+
console.log('Page Changed:', currentPage, 'Total:', totalPages);
|
|
173
|
+
});
|
|
174
|
+
|
|
175
|
+
// To unsubscribe:
|
|
176
|
+
unsubscribe();
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Supported events: `init`, `progress`, `pageChange`, `zoomChange`, `singlePageModeChange`, `thumbsToggle`, `tocToggle`, `orientationChange`, `error`, `destroy`.
|
|
180
|
+
|
|
181
|
+
| Option | Type | Default | Description |
|
|
182
|
+
| :--- | :--- | :--- | :--- |
|
|
183
|
+
| `showArrows` | `boolean` | `true` | Shows the previous/next navigation arrows. |
|
|
184
|
+
| `showToc` | `boolean` | `false` | Shows the table of contents panel when `toc` entries are supplied. |
|
|
185
|
+
| `toc` | `FlipbookTocEntry[]` | `[]` | Host-provided chapter/category entries with zero-based page indexes. |
|
|
186
|
+
| `soundEnabled` | `boolean` | `true` | Enables page turning sound effect. |
|
|
187
|
+
| `soundUrl` | `string` | `'https://.../page-flip.mp3'` | URL of the audio file. |
|
|
188
|
+
| `autoPlayInterval`| `number` | `3000` | Autoplay page duration in milliseconds. |
|
|
189
|
+
| `flippingTime` | `number` | `1000` | Duration of the page turn animation in milliseconds; automatically disabled when reduced motion is preferred. |
|
|
190
|
+
| `maxShadowOpacity` | `number` | `0.5` | Maximum opacity of the shadow during page turn (0 to 1). |
|
|
191
|
+
| `whiteLabel` | `boolean` | `false` | Hides the "Powered by FlipbookEngine" watermark. |
|
|
192
|
+
| `pdfWorkerSrc` | `string` | - | URL of the PDF.js worker emitted or hosted by the consuming application. |
|
|
193
|
+
| `pdfRenderConcurrency` | `number` | `3` | Maximum number of PDF pages rendered concurrently when on-demand pages are requested. |
|
|
194
|
+
| `pdfRenderCacheSize` | `number` | `32` | Maximum number of rendered PDF page images retained per engine instance (LRU); `0` disables caching. |
|
|
195
|
+
|
|
196
|
+
## Styling and Theming
|
|
197
|
+
|
|
198
|
+
FlipbookEngine features fully custom-property-based styling compatible with modern styling systems.
|
|
199
|
+
|
|
200
|
+
### Global CSS Variables
|
|
201
|
+
|
|
202
|
+
```css
|
|
203
|
+
:root {
|
|
204
|
+
--mainbgcolor: #f3f6fb;
|
|
205
|
+
--panelbgcolor: #172033;
|
|
206
|
+
--flipbook-accent: #7367f0;
|
|
207
|
+
--thumbrailbgcolor: #0f172a;
|
|
208
|
+
}
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## Performance & Bundle Metrics
|
|
212
|
+
|
|
213
|
+
FlipbookEngine is designed for responsive rendering with hardware-accelerated CSS 3D transforms and a lightweight DOM update path.
|
|
214
|
+
|
|
215
|
+
### Package Size and PDF.js
|
|
216
|
+
|
|
217
|
+
FlipbookEngine does not bundle PDF.js or its worker. `pdfjs-dist` remains a normal npm dependency, while the host application supplies `pdfWorkerSrc`. This keeps the FlipbookEngine package smaller and lets the application control PDF.js versioning, caching, CSP, and worker hosting.
|
|
218
|
+
|
|
219
|
+
* **Core engine:** excludes PDF.js and the PDF worker.
|
|
220
|
+
* **Styles:** distributed as `flipbookengine/styles.css`.
|
|
221
|
+
* **PDF rendering:** enabled by configuring `pdfWorkerSrc` as shown above.
|
|
222
|
+
|
|
223
|
+
### Performance Highlights
|
|
224
|
+
* **Hardware Accelerated:** Uses CSS-based 3D transformations (`transform: rotateY`, `translateZ`) without a WebGL runtime.
|
|
225
|
+
* **Progressive Image Quality:** Loads low-quality page assets first and upgrades visible pages to their normal-quality source through `IntersectionObserver`.
|
|
226
|
+
* **On-demand PDF Rendering:** Large PDFs create lightweight placeholders first; the current page and next page render before or during navigation.
|
|
227
|
+
* **Bounded PDF Rendering:** PDF pages are rendered with configurable concurrency (`pdfRenderConcurrency`, default `3`) and can be cancelled when an initialization is superseded or destroyed.
|
|
228
|
+
* **PDF Render Cache:** A bounded per-instance LRU cache (`pdfRenderCacheSize`, default `32`) avoids repeated canvas work while preventing unbounded memory growth.
|
|
229
|
+
|
|
230
|
+
## FlipbookEngine vs. The Industry
|
|
231
|
+
|
|
232
|
+
When choosing a flipbook library, here is how we compare to other solutions:
|
|
233
|
+
|
|
234
|
+
* **Legacy Libraries (e.g., Turn.js):** Turn.js is over a decade old, relies on jQuery, and lacks native PDF support. **FlipbookEngine** uses a modern framework-agnostic stack (Vanilla/React/Vue), TypeScript, and has built-in PDF.js integration.
|
|
235
|
+
* **Heavy 3D Plugins (e.g., DearFlip, Real3D):** Many 3D plugins use WebGL, which can increase runtime overhead on mobile. **FlipbookEngine** uses StPageFlip with CSS 2D/3D transforms and no WebGL runtime.
|
|
236
|
+
* **Closed SaaS Platforms (e.g., Issuu, Heyzine):** These charge high monthly fees and lock your data on their servers. **FlipbookEngine** gives you 100% control to host and embed directly in your own code (AGPL-3.0).
|
|
237
|
+
|
|
238
|
+
---
|
|
239
|
+
|
|
240
|
+
## Acknowledgments
|
|
241
|
+
|
|
242
|
+
A special thanks to the incredible team behind **[Serenity](https://github.com/serenity-is/serenity)**. FlipbookEngine's reactive UI layer is powered by **[domwise](https://github.com/serenity-is/serenity/tree/master/packages/domwise)**. Coupled with `@preact/signals-core`, this keeps the UI update path small without requiring a traditional Virtual DOM runtime.
|
|
243
|
+
|
|
244
|
+
---
|
|
240
245
|
## Roadmap
|
|
241
246
|
|
|
242
247
|
FlipbookEngine has two complementary targets: an AGPL open-source viewer package and a separate closed-source commercial backend edition.
|
|
@@ -264,16 +269,16 @@ The commercial roadmap is separate from the AGPL package and is intended for a s
|
|
|
264
269
|
|
|
265
270
|
These backend renderer and enterprise features will not be included in the public `flipbookengine` npm package; they will be delivered under the commercial license.
|
|
266
271
|
|
|
267
|
-
---
|
|
268
|
-
|
|
269
|
-
## Licensing
|
|
270
|
-
|
|
271
|
-
FlipbookEngine is distributed under a dual-license model:
|
|
272
|
-
|
|
273
|
-
- **Open Source**: GNU Affero General Public License v3.0 or later (see [LICENSE](./LICENSE)).
|
|
274
|
-
- **Commercial**: For use in closed-source projects, proprietary SaaS platforms, or agency client deliveries (see [COMMERCIAL_LICENSE.md](./COMMERCIAL_LICENSE.md)).
|
|
275
|
-
|
|
276
|
-
For commercial licenses and inquiries, contact: **murat.dogan@hotmail.com.tr**
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
272
|
+
---
|
|
273
|
+
|
|
274
|
+
## Licensing
|
|
275
|
+
|
|
276
|
+
FlipbookEngine is distributed under a dual-license model:
|
|
277
|
+
|
|
278
|
+
- **Open Source**: GNU Affero General Public License v3.0 or later (see [LICENSE](./LICENSE)).
|
|
279
|
+
- **Commercial**: For use in closed-source projects, proprietary SaaS platforms, or agency client deliveries (see [COMMERCIAL_LICENSE.md](./COMMERCIAL_LICENSE.md)).
|
|
280
|
+
|
|
281
|
+
For commercial licenses and inquiries, contact: **murat.dogan@hotmail.com.tr**
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
|