pdfjs-viewer-element 3.1.0 → 3.1.1

package/README.md

@@ -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 |
@@ -106,9 +115,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 +131,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 +162,63 @@ Build your own theme with viewer custom variables and inject it via `injectViewe
 }
 ```
 
-## Methods
+## Methods and Public properties
 
-`injectViewerStyles(styles: string)` - Adds custom CSS to the viewer now (when ready) and for future rebuilds.
+Methods:
 
-## Programmatic access to PDF.js
+`injectViewerStyles(styles: string)` - Adds custom CSS to the viewer now (when ready) and for future rebuilds.
 
-```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 })
-  })
-})
-```
-
-You can also react to source changes dynamically:
+const viewerElement = document.querySelector('pdfjs-viewer-element')
 
-```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')
+viewer.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)