react-pdfjs-multi 1.0.0-rc.4 → 1.0.0-rc.5

package/README.md

@@ -2,64 +2,86 @@
 
 React wrapper for pdfjs with multiple file support.
 
-This library uses [pdf.js][1].
+You can find a working example [here][2].
 
-> What does in development mean:
->
-> 1.  **MINOR** versions represent **breaking changes**
-> 1.  **PATCH** versions represent **fixes _and_ features**
-> 1.  There are **no deprecation warnings** between releases
+This library uses [pdf.js][1].
 
 ## Installation & Usage
 
-`yarn add react-pdfjs-multi`
+`npm i react-pdfjs-multi`
 
-or
+### Example Usage
 
-`npm i react-pdfjs-multi`
+#### Minimal example
 
-Example Usage MultiViewer:
+If you only need the defaults, you can render the component with just the `pdfs` array and the bundled CSS.
 
-```javascript
+```tsx
 import React from 'react';
 import { PdfMultiViewer } from 'react-pdfjs-multi';
+import workerSrc from 'react-pdfjs-multi/dist/pdf.worker.min.mjs?url';
 import 'react-pdfjs-multi/dist/react-pdfjs-multi.css';
 
-const MultiViewerExample = () => {
-  const pdfFiles = [
-    'pdfs/test-pdf-a.pdf',
-    {
-      title:
-        'Trace-based Just-in-Time Type Specialization for DynamicLanguages',
-      source: 'pdfs/compressed.tracemonkey-pldi-09.pdf',
-    },
-    'pdfs/test-pdf-b.pdf',
-    'pdfs/test-pdf-c.pdf',
-  ];
-
-  return (
-    <PdfMultiViewer
-      pdfs={pdfFiles}
-      i18nData={{
-        download: 'Herunterladen',
-        scaleDown: 'Verkleinern',
-        scaleUp: 'Vergrößern',
-        originalSize: 'Originalgröße',
-        pages: 'Seiten',
-        zoom: 'Automatischer Zoom',
-      }}
-    />
-  );
+const MinimalMultiViewer = () => (
+  <PdfMultiViewer pdfs={['/pdfs/sample-a.pdf', '/pdfs/sample-b.pdf']} />
+);
+
+export default MinimalMultiViewer;
+```
+
+#### MultiViewer customization
+
+This example picks a non-default document via `initialLoadIndex`, and the `icons` prop overrides the visual assets via CSS variables.
+
+```tsx
+import React from 'react';
+import { PdfMultiViewer, type IconConfig } from 'react-pdfjs-multi';
+import workerSrc from 'react-pdfjs-multi/dist/pdf.worker.min.mjs?url';
+import 'react-pdfjs-multi/dist/react-pdfjs-multi.css';
+
+const pdfs = ['/pdfs/sample-a.pdf', '/pdfs/sample-b.pdf'];
+
+const icons: IconConfig = {
+  zoomIn: '/icons/zoom-in.svg',
+  zoomOut: '/icons/zoom-out.svg',
+  rotateLeft: '/icons/rotate-left.svg',
+  rotateRight: '/icons/rotate-right.svg',
+  download: '/icons/download.svg',
+  toggleList: '/icons/toggle-list.svg',
+  selectArrow: '/icons/select-arrow.svg',
+  texture: 'none',
 };
 
+const MultiViewerExample = () => (
+  <PdfMultiViewer
+    pdfs={pdfs}
+    workerSrc={workerSrc}
+    icons={icons}
+    rendererIcons={icons}
+    initialLoadIndex={1}
+    i18nData={{
+      download: 'Download',
+      scaleDown: 'Scale down',
+      scaleUp: 'Scale up',
+    }}
+  />
+);
+
 export default MultiViewerExample;
 ```
 
-Example Usage Renderer (Typescript)
+#### PdfRenderer integration
 
-```typescript
-import React, { FC, useState, useEffect } from 'react';
-import { PdfRenderer, PdfjsLib, PDFDocumentProxy } from 'react-pdfjs-multi';
+When building your own viewer, assign the worker once and listen to the `pdfChangeHook` if you need to cache zoom/rotation/scroll positions manually.
+
+```tsx
+import React, { FC, useEffect, useState } from 'react';
+import {
+  PdfRenderer,
+  PdfjsLib,
+  type PDFDocumentProxy,
+  type RendererDocumentPosition,
+} from 'react-pdfjs-multi';
 import workerSrc from 'react-pdfjs-multi/dist/pdf.worker.min.mjs?url';
 
 PdfjsLib.GlobalWorkerOptions.workerSrc = workerSrc;
@@ -67,21 +89,25 @@ PdfjsLib.GlobalWorkerOptions.workerSrc = workerSrc;
 const RendererExample: FC = () => {
   const [pdfDoc, setPdfDoc] = useState<PDFDocumentProxy>();
 
+  const logPosition = (index: string, position: RendererDocumentPosition) => {
+    console.log('document position', index, position);
+  };
+
   useEffect(() => {
-    const getPdfDoc = async () => {
+    const load = async () => {
       const doc = await PdfjsLib.getDocument({
-        url: 'pdfs/compressed.tracemonkey-pldi-09.pdf',
+        url: '/pdfs/sample-a.pdf',
       }).promise;
 
       setPdfDoc(doc);
     };
 
-    getPdfDoc();
+    load();
   }, []);
 
   if (!pdfDoc) return null;
 
-  return <PdfRenderer pdfDoc={pdfDoc} downloadBtn={false} />;
+  return <PdfRenderer pdfDoc={pdfDoc} downloadBtn pdfChangeHook={logPosition} />;
 };
 
 export default RendererExample;
@@ -91,14 +117,15 @@ export default RendererExample;
 
 A minimal workspace example lives at `apps/example`.
 
+- `apps/example/src/examples/DefaultExample.tsx`
+- `apps/example/src/examples/ContrastExample.tsx` + `ContrastExample.css`
+
 ```bash
 pnpm install
 pnpm start
 pnpm dev:example
 ```
 
-Run `pnpm start` and `pnpm dev:example` in separate terminals during development.
-
 ### Styling
 
 This library ships with optional default styles in
@@ -119,6 +146,70 @@ Example override:
 }
 ```
 
+#### Theming recipe (example)
+
+Here is a compact “high-contrast” pattern similar to the example app. It uses
+icon overrides, CSS variables, and a scoped theme class:
+
+```tsx
+import React from 'react';
+import type { IconConfig } from 'react-pdfjs-multi';
+import { PdfMultiViewer } from 'react-pdfjs-multi';
+
+const icons: IconConfig = {
+  zoomIn: '/icons/zoom-in.svg',
+  zoomOut: '/icons/zoom-out.svg',
+  rotateLeft: '/icons/rotate-left.svg',
+  rotateRight: '/icons/rotate-right.svg',
+  download: '/icons/download.svg',
+  toggleList: '/icons/toggle-list.svg',
+  selectArrow: '/icons/select-arrow.svg',
+};
+
+const viewerStyle = {
+  '--pdfjs-multi-bg': '#0a0f1c',
+  '--pdfjs-multi-texture': 'none',
+  '--pdfjs-multi-text': '#e2e8f0',
+  '--pdfjs-multi-surface': 'rgba(15, 23, 42, 0.9)',
+  '--pdfjs-multi-surface-active': 'rgba(30, 41, 59, 0.92)',
+  '--pdfjs-multi-muted-text': '#94a3b8',
+} as const;
+
+const rendererStyle = {
+  '--pdfjs-multi-controls-bg': '#0f172a',
+  '--pdfjs-multi-controls-text': '#f8fafc',
+  '--pdfjs-multi-control-icon-size': '18px',
+  '--pdfjs-multi-select-text': '#f8fafc',
+} as const;
+
+const HighContrastViewer = () => (
+  <div className="theme-contrast">
+    <PdfMultiViewer
+      pdfs={['/pdfs/sample-a.pdf', '/pdfs/sample-b.pdf']}
+      icons={icons}
+      rendererIcons={icons}
+      style={viewerStyle}
+      rendererStyle={rendererStyle}
+    />
+  </div>
+);
+```
+
+```css
+.theme-contrast .renderer-controls {
+  /* renderer-controls defines its own icon vars, so inherit in themed skins */
+  --pdfjs-multi-control-icon-zoom-out: inherit;
+  --pdfjs-multi-control-icon-zoom-in: inherit;
+  --pdfjs-multi-control-icon-rotate-left: inherit;
+  --pdfjs-multi-control-icon-rotate-right: inherit;
+  --pdfjs-multi-control-icon-download: inherit;
+}
+
+.theme-contrast .dropdown-toolbar-container {
+  --pdfjs-multi-select-icon: inherit;
+}
+```
+
 Available variables (non-exhaustive):
 
 | Scope | Variable | Default | Purpose |
@@ -166,24 +257,35 @@ const icons: IconConfig = {
 };
 ```
 
+If you want the same icon set applied to the renderer controls, pass
+`rendererIcons` to `PdfMultiViewer` (or use `icons` directly on `PdfRenderer`).
+
 ### PdfMultiViewer
 
-The MultiViewer allows you to pass an array of source strings or an object definition and it lazy-loads PDFs by default, showing the renderer as soon as the active PDF is loaded.
+The MultiViewer allows you to pass an array of source strings or objects (optionally with a custom `title`) and it lazy-loads PDFs by default, showing the renderer as soon as the active PDF is loaded.
+The list is guarded by the toggle in the option bar; on widths between ~330px and ~667px it switches into an overlay so the renderer keeps the extra space, and selecting a document when the list is overlaid closes it automatically. The viewer also records zoom, rotation, and scroll positions per document via the embedded `pdfChangeHook`, so revisiting a PDF restores the position you left it in.
 
 Props:
 
 | Name            | Required | Default | Type            | Description                                                    |
 | --------------- | -------- | ------- | --------------- | -------------------------------------------------------------- |
-| pdfs            | true     |         | {array}         | An array of strings or objects                                 |
+| pdfs            | true     |         | {array}         | Strings or `{ source, title? }` objects for each PDF           |
 | autoZoom        |          | true    | {boolean}       | enables/disables autoZoom on component mount and window resize |
+| className       |          |         | {string}        | Adds a class to the outer viewer container                     |
 | controls        |          | true    | {boolean}       | enables/disables controls to e.g. change renderer zoom         |
 | icons           |          |         | {IconConfig}    | Override default icons and texture                             |
+| rendererIcons   |          |         | {IconConfig}    | Override renderer control icons                                |
+| rendererClassName |        |         | {string}        | Adds a class to the renderer container                         |
+| rendererStyle   |          |         | {CSSProperties} | Inline styles for the renderer container                       |
 | i18nData        |          | {}\*    | {I18nData}      | An object of translated strings, default language is en        |
 | startIndex      |          | 0       | {number}        | first pdf to display using array index                         |
 | lazyLoad        |          | true    | {boolean}       | load only the active PDF until a list item is selected         |
 | initialLoadIndex|          | startIndex | {number|string} | which PDF to prefetch on mount when lazyLoad is enabled     |
+| style           |          |         | {CSSProperties} | Inline styles for the outer viewer container                   |
 | workerSrc       |          |         | {string}        | pdf.js worker URL                                              |
 
+When `lazyLoad` is enabled (the default), you can use `initialLoadIndex` to prime a different PDF than the one shown first, and `PdfMultiViewer` already passes its own `pdfChangeHook` to `PdfRenderer` so zoom/rotation/scroll state is cached automatically; you only need to provide your own hook if you want that data for something else.
+
 ### i18n
 
 To be able to use different i18n libraries eg. i18next or react-intl you can pass an i18n object with translated strings to the component.
@@ -216,10 +318,12 @@ Props:
 | ------------- | -------- | ------- | ------------------ | -------------------------------------------------------------- |
 | pdfDoc        | true     |         | {PDFDocumentProxy} | A proxy of the pdf document to display                         |
 | autoZoom      |          | true    | {boolean}          | enables/disables autoZoom on component mount and window resize |
+| className     |          |         | {string}           | Adds a class to the renderer container                         |
 | controls      |          | true    | {boolean}          | enables/disables controls to e.g. change renderer zoom         |
 | downloadBtn   |          | true    | {boolean}          | enables/disables download button                               |
 | icons         |          |         | {IconConfig}       | Override default icons and texture                             |
 | i18nData      |          | {}\*    | {I18nDataRenderer} | An object of translated strings, default language is en        |
+| style         |          |         | {CSSProperties}    | Inline styles for the renderer container                       |
 | zoom          |          | null    | {number}           | Initial Zoom                                                   |
 | rotation      |          | null    | {number}           | Initial Rotation                                               |
 | scrollTop     |          | null    | {number}           | Initial ScrollTop                                              |
@@ -228,3 +332,4 @@ Props:
 | pdfChangeHook |          | null    | {func}             | Callback function which gets a position object                 |
 
 [1]: https://mozilla.github.io/pdf.js/
+[2]: https://optimisticupdate.github.io/react-pdfjs-multi/

package/dist/components/PdfMultiViewer/PdfMultiViewer.d.ts

@@ -1,12 +1,18 @@
+import type { CSSProperties } from 'react';
 import '@/components/PdfMultiViewer/PdfMultiViewer.css';
 import { type I18nData, type PdfSource } from '@/components/PdfMultiViewer/usePdfMultiViewer';
 import type { IconConfig } from '@/types/iconConfig';
 type DefaultProps = {
     autoZoom?: boolean;
+    className?: string;
     controls?: boolean;
     icons?: IconConfig;
     lazyLoad?: boolean;
     initialLoadIndex?: string | number;
+    rendererIcons?: IconConfig;
+    rendererClassName?: string;
+    rendererStyle?: CSSProperties;
+    style?: CSSProperties;
     startIndex?: string;
     i18nData?: I18nData;
     workerSrc?: string;
@@ -14,6 +20,6 @@ type DefaultProps = {
 type Props = {
     pdfs: PdfSource[];
 } & Partial<DefaultProps>;
-declare const PdfMultiViewer: ({ pdfs, autoZoom, controls, icons, lazyLoad, initialLoadIndex, startIndex, i18nData, workerSrc, }: Props) => import("react/jsx-runtime").JSX.Element;
+declare const PdfMultiViewer: ({ pdfs, autoZoom, className, controls, icons, lazyLoad, initialLoadIndex, rendererIcons, rendererClassName, rendererStyle, style, startIndex, i18nData, workerSrc, }: Props) => import("react/jsx-runtime").JSX.Element;
 export default PdfMultiViewer;
 export type { I18nData };

package/dist/components/PdfMultiViewer/PdfMultiViewerView.d.ts

@@ -1,9 +1,11 @@
 import type { CSSProperties, RefObject } from 'react';
 import type { I18nData, PdfFile } from '@/components/PdfMultiViewer/usePdfMultiViewer';
 import type { RendererDocumentPosition } from '@/components/PdfRenderer/usePdfRenderer';
+import type { IconConfig } from '@/types/iconConfig';
 type Props = {
     activeIndex: string;
     autoZoom: boolean;
+    className?: string;
     controls: boolean;
     files: PdfFile[];
     iconStyles?: CSSProperties;
@@ -11,10 +13,13 @@ type Props = {
     listVisible: boolean;
     overlayMode: boolean;
     pdfToShow?: PdfFile;
+    rendererIcons?: IconConfig;
+    rendererClassName?: string;
+    rendererStyle?: CSSProperties;
     viewerContainerRef: RefObject<HTMLDivElement>;
     onRememberPosition: (index: string, position: RendererDocumentPosition) => void;
     onSelectPdf: (nextIndex: string, file: PdfFile) => () => void;
     onToggleList: () => void;
 };
-declare const PdfMultiViewerView: ({ activeIndex, autoZoom, controls, files, iconStyles, i18nData, listVisible, overlayMode, pdfToShow, viewerContainerRef, onRememberPosition, onSelectPdf, onToggleList, }: Props) => import("react/jsx-runtime").JSX.Element;
+declare const PdfMultiViewerView: ({ activeIndex, autoZoom, className, controls, files, iconStyles, i18nData, listVisible, overlayMode, pdfToShow, rendererIcons, rendererClassName, rendererStyle, viewerContainerRef, onRememberPosition, onSelectPdf, onToggleList, }: Props) => import("react/jsx-runtime").JSX.Element;
 export default PdfMultiViewerView;

package/dist/components/PdfMultiViewer/usePdfMultiViewer.d.ts

@@ -2,7 +2,7 @@ import type { PDFDocumentProxy } from 'pdfjs-dist';
 import type { RendererDocumentPosition } from '@/components/PdfRenderer/usePdfRenderer';
 import type { I18nDataRenderer } from '@/contexts';
 export type PdfDefinition = {
-    title: string;
+    title?: string;
     source: string;
 };
 export type PdfSource = string | PdfDefinition;
@@ -35,7 +35,7 @@ export declare const usePdfMultiViewer: ({ pdfs, startIndex, i18nData, lazyLoad,
     i18nData: I18nData;
     listVisible: boolean;
     overlayMode: boolean;
-    pdfToShow: PdfFile;
+    pdfToShow: PdfFile | undefined;
     rememberPosition: (index: string, position: RendererDocumentPosition) => void;
     selectPdf: (nextIndex: string, file: PdfFile) => () => void;
     toggleList: () => void;

package/dist/components/PdfRenderer/PdfRenderer.d.ts

@@ -1,5 +1,6 @@
 import type { PDFDocumentProxy } from 'pdfjs-dist';
 import type { PDFViewer } from 'pdfjs-dist/web/pdf_viewer.mjs';
+import type { CSSProperties } from 'react';
 import 'pdfjs-dist/web/pdf_viewer.css';
 import '@/components/PdfRenderer/PdfRenderer.css';
 import { type PdfChangeHook } from '@/components/PdfRenderer/usePdfRenderer';
@@ -9,11 +10,13 @@ export type { RendererDocumentPosition } from '@/components/PdfRenderer/usePdfRe
 type DefaultProps = {
     activeIndex?: string;
     autoZoom?: boolean;
+    className?: string;
     controls?: boolean;
     downloadBtn: boolean;
     icons?: IconConfig;
     i18nData?: I18nDataRenderer;
     pdfChangeHook?: PdfChangeHook | null;
+    style?: CSSProperties;
     zoom?: number;
     rotation?: number;
     scrollTop?: number | null;

package/dist/components/PdfRenderer/PdfRendererControls.d.ts

@@ -1,7 +1,9 @@
+import type { CSSProperties } from 'react';
 import '@/components/PdfRenderer/PdfRendererControls.css';
 type Props = {
     autoZoom?: boolean;
     downloadBtn?: boolean;
+    iconStyles?: CSSProperties;
     onDownload: () => void;
     onZoomIn: () => void;
     onZoomOut: () => void;
@@ -10,5 +12,5 @@ type Props = {
     scale: number;
     setScale: (scale: number) => void;
 };
-declare const PdfControls: ({ autoZoom, downloadBtn, onDownload, onZoomIn, onZoomOut, onRotateRight, onRotateLeft, scale, setScale, }: Props) => import("react/jsx-runtime").JSX.Element;
+declare const PdfControls: ({ autoZoom, downloadBtn, iconStyles, onDownload, onZoomIn, onZoomOut, onRotateRight, onRotateLeft, scale, setScale, }: Props) => import("react/jsx-runtime").JSX.Element;
 export default PdfControls;

package/dist/components/PdfRenderer/PdfRendererView.d.ts

@@ -2,6 +2,7 @@ import type { CSSProperties, RefObject } from 'react';
 import { type I18nDataRenderer } from '@/contexts';
 type Props = {
     autoZoom: boolean;
+    className?: string;
     containerRef: RefObject<HTMLDivElement>;
     controls: boolean;
     downloadBtn: boolean;
@@ -16,5 +17,5 @@ type Props = {
     onZoomIn: () => void;
     onZoomOut: () => void;
 };
-declare const PdfRendererView: ({ autoZoom, containerRef, controls, downloadBtn, iconStyles, i18nData, isLoading, scale, setScale, onDownload, onRotateLeft, onRotateRight, onZoomIn, onZoomOut, }: Props) => import("react/jsx-runtime").JSX.Element;
+declare const PdfRendererView: ({ autoZoom, className, containerRef, controls, downloadBtn, iconStyles, i18nData, isLoading, scale, setScale, onDownload, onRotateLeft, onRotateRight, onZoomIn, onZoomOut, }: Props) => import("react/jsx-runtime").JSX.Element;
 export default PdfRendererView;