pdfjs-viewer-element 3.1.0 → 3.1.2

package/README.md

@@ -14,11 +14,11 @@ Supported in all [major browsers](https://caniuse.com/custom-elementsv1), and wo
 
 ## Features
 
-- Standalone web component with no runtime dependencies
+- Standalone isolated web component with no runtime dependencies
 - Drop-in, iframe-based PDF.js default viewer for any web app
 - Works with same-origin and cross-origin PDF documents
 - Configure via attributes and URL parameters (page, zoom, search, pagemode, locale)
-- Programmatic access to `PDFViewerApplication` and `PDFViewerApplicationOptions` via the `initialized` event
+- Programmatic access to `PDFViewerApplication` via the `initPromise` public property
 - Theme control (automatic/light/dark) plus custom CSS injection
 - Locale override support using PDF.js viewer locales
 - Supports all modern browsers and most JS frameworks
@@ -31,7 +31,11 @@ Supported in all [major browsers](https://caniuse.com/custom-elementsv1), and wo
 
 [CodePen demo](https://codepen.io/redrobot753/pen/bNwVVvp)
 
-[Various use cases](https://github.com/alekswebnet/pdfjs-viewer-element/tree/master/demo)
+[CodePen demo with React](https://codepen.io/redrobot753/pen/xbEwNrO)
+
+[CodePen demo with Vue](https://codepen.io/redrobot753/pen/JoRYqwN)
+
+[Usage examples](https://github.com/alekswebnet/pdfjs-viewer-element/tree/master/demo)
 
 ## Install
 
@@ -58,13 +62,18 @@ import 'pdfjs-viewer-element'
 
 ```html
 <pdfjs-viewer-element
-  src="/sample.pdf"
+  src="https://alekswebnet.github.io/sample-pdf-with-images.pdf"
   style="height: 100dvh">
 </pdfjs-viewer-element>
 ```
 
 The element is block-level and needs an explicit height.
 
+### Framework usage
+
+- [React integration example](https://codepen.io/redrobot753/pen/xbEwNrO)
+- [Vue integration example](https://codepen.io/redrobot753/pen/JoRYqwN)
+
 ## Attributes
 
 | Attribute | Description | Default |
@@ -77,8 +86,9 @@ The element is block-level and needs an explicit height.
 | `zoom` | Zoom level (for example `auto`, `page-width`, `200%`). | `''` |
 | `pagemode` | Sidebar mode: `thumbs`, `bookmarks`, `attachments`, `layers`, `none`. | `none` |
 | `locale` | Viewer UI locale (for example `en-US`, `de`, `uk`). [Available locales](https://github.com/mozilla/pdf.js/tree/master/l10n) | `''` |
+| `locale-src-template` | Locale file URL template. Must contain `{locale}` placeholder. Used together with `locale`. | `https://cdn.jsdelivr.net/gh/mozilla-l10n/firefox-l10n@main/{locale}/toolkit/toolkit/pdfviewer/viewer.ftl` |
 | `viewer-css-theme` | Viewer theme: `AUTOMATIC`, `LIGHT`, `DARK`. | `AUTOMATIC` |
-| `worker-src` | PDF.js worker URL override. | `https://cdn.jsdelivr.net/npm/pdfjs-dist@5.4.624/build/pdf.worker.min.mjs` |
+| `worker-src` | PDF.js worker URL override. | `<package-url>/pdf.worker.min.mjs` |
 
 Play with attributes on [API docs page](https://alekswebnet.github.io/pdfjs-viewer-element/#api).
 
@@ -92,6 +102,41 @@ Most attributes can be updated dynamically:
 - `worker-src` updates viewer options for subsequent document loads.
 - `locale` rebuilds the viewer so localization resources can be applied.
 
+## Worker source
+
+By default, the component resolves `worker-src` to the worker shipped with this package (`pdf.worker.min.mjs` in `dist`).
+
+Set `worker-src` only if you want to serve the worker from a custom location (for example your own CDN or static assets path).
+
+- The URL must point to a valid PDF.js module worker file.
+- The worker version should match the bundled PDF.js version.
+
+```html
+<pdfjs-viewer-element
+  src="/file.pdf"
+  worker-src="https://cdn.jsdelivr.net/npm/pdfjs-dist@5.5.207/build/pdf.worker.min.mjs">
+</pdfjs-viewer-element>
+```
+
+## Locale source template
+
+Use `locale-src-template` when you need to load localization files from a custom host.
+
+- The template must include `{locale}`.
+- `{locale}` is replaced by the `locale` attribute value (for example `de`, `uk`, `en-US`).
+- If `locale` is not set, no locale file is loaded.
+- Changes to `locale-src-template` are applied when the viewer is (re)initialized, for example after setting/changing `locale`.
+
+Example:
+
+```html
+<pdfjs-viewer-element
+  src="/file.pdf"
+  locale="de"
+  locale-src-template="https://cdn.example.com/pdfjs-locales/{locale}/viewer.ftl">
+</pdfjs-viewer-element>
+```
+
 ## Viewer CSS theme
 
 Use `viewer-css-theme` attribute to set light or dark theme manually:
@@ -106,9 +151,10 @@ Use `viewer-css-theme` attribute to set light or dark theme manually:
 Runtime example:
 
 ```javascript
-const viewer = document.querySelector('pdfjs-viewer-element')
-viewer.setAttribute('viewer-css-theme', 'DARK')
-viewer.setAttribute('viewer-css-theme', 'AUTOMATIC')
+const viewerElement = document.querySelector('pdfjs-viewer-element')
+viewerElement.setAttribute('viewer-css-theme', 'DARK')
+viewerElement.setAttribute('viewer-css-theme', 'LIGHT')
+viewerElement.setAttribute('viewer-css-theme', 'AUTOMATIC')
 ```
 
 ## Viewer custom styles
@@ -121,8 +167,8 @@ You can add your own CSS rules to the viewer application using `injectViewerStyl
 ```
 
 ```javascript
-const viewer = document.querySelector('#viewer')
-viewer.injectViewerStyles(`
+const viewerElement = document.querySelector('#viewer')
+viewerElement.injectViewerStyles(`
   #toolbarViewerMiddle, #toolbarViewerRight { display: none; }
 `)
 ```
@@ -152,89 +198,63 @@ Build your own theme with viewer custom variables and inject it via `injectViewe
 }
 ```
 
-## Methods
+## Methods and Public properties
+
+Methods:
 
 `injectViewerStyles(styles: string)` - Adds custom CSS to the viewer now (when ready) and for future rebuilds.
 
-## Programmatic access to PDF.js
-
-```html
-<pdfjs-viewer-element></pdfjs-viewer-element>
-```
+Example (`injectViewerStyles`):
 
 ```javascript
-// Open PDF file programmatically accessing the viewer application
-document.addEventListener('DOMContentLoaded', async () => {
-  document.querySelector('pdfjs-viewer-element').addEventListener('initialized', (event) => {
-    const { viewerApp, viewerOptions } = event.detail
-    viewerApp.open({ data: pdfData })
-  })
-})
-```
+const viewerElement = document.querySelector('pdfjs-viewer-element')
 
-You can also react to source changes dynamically:
-
-```javascript
-const viewer = document.querySelector('pdfjs-viewer-element')
-viewer.setAttribute('src', '/another-file.pdf')
+await viewerElement.injectViewerStyles(`
+  #toolbarViewerRight { display: none; }
+  #findbar { border-top: 2px solid #0200a8; }
+`)
 ```
 
-## Events
-
-`initialized` - Fired after the PDF.js viewer is ready (after `PDFViewerApplication.initializedPromise` resolves). The event `detail` contains:
-
-- `viewerApp` (`PDFViewerApplication`)
-- `viewerOptions` (`PDFViewerApplicationOptions`)
+Public properties:
 
-The event is emitted each time the internal viewer is rebuilt (for example after changing `locale`).
+`initPromise: Promise<InitializationData>` - Resolves after internal viewer is completely loaded and initialized, returning `{ viewerApp }`, that gives a programmatic access to PDF.js viewer app (PDFViewerApplication).
 
-## Migration notes
+Example (`initPromise`):
 
-If you are upgrading from an older version:
-
-- `viewer-extra-styles` and `viewer-extra-styles-urls` attributes are removed.
-- Use `injectViewerStyles(styles)` instead of style attributes.
-- Use the `initialized` event for `viewerApp` / `viewerOptions` access.
-- Runtime `src` updates are supported with `setAttribute('src', ...)`.
-
-## Accessibility
+```javascript
+const viewerElement = document.querySelector('pdfjs-viewer-element')
+const { viewerApp } = await viewerElement.initPromise
 
-Use `iframe-title` to add a title to the `iframe` element and improve accessibility.
+viewerApp.open({ url: '/sample.pdf' })
+```
 
-## Known issues
+`iframe: PdfjsViewerElementIframe` - Public reference to the internal `iframe` element. Useful when you need direct access to `contentWindow`/`contentDocument`.
 
-### The `.mjs` files support
+Example (`iframe`):
 
-Since v4 PDF.js requires `.mjs` files support, make sure your server has it.
+```javascript
+const viewerElement = document.querySelector('pdfjs-viewer-element')
 
-In case of `nginx` this may cause errors, see https://github.com/mozilla/pdf.js/issues/17296
+// Access iframe window directly when needed.
+const iframeWindow = viewerElement.iframe.contentWindow
 
-Add `.mjs` files support for `nginx` example:
+// Read current location hash applied to the viewer.
+console.log(iframeWindow.location.hash)
 
-```bash
-server {
-    # ...
-
-    location / {
-        root   /usr/share/nginx/html;
-        index  index.html;
-
-        location ~* \.mjs$ {
-            types {
-                text/javascript mjs;
-            }
-        }
-    }
-}
+// Inspect iframe document title.
+console.log(viewerElement.iframe.contentDocument.title)
 ```
 
-## Support via Ko-fi
+You can also react to source changes dynamically:
 
-If you find `pdfjs-viewer-element` useful and want to support its development, consider making a donation via Ko-fi:
+```javascript
+const viewerElement = document.querySelector('pdfjs-viewer-element')
+viewerElement.setAttribute('src', '/another-file.pdf')
+```
 
-[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/oleksandrshevchuk)
+## Accessibility
 
-> ❤️ Your support helps with maintenance, bug fixes, and long-term improvements.
+Use `iframe-title` to add a title to the `iframe` element and improve accessibility.
 
 ## License
 [MIT](http://opensource.org/licenses/MIT)