@kingtech/react-pdf-viewer 0.0.0-stage → 1.0.0

package/dist/core/pdfjs.d.ts

@@ -0,0 +1,80 @@
+import { PdfJsDocumentOptions } from '../types.js';
+import type * as PdfJsNamespace from 'pdfjs-dist';
+/** The `pdfjs-dist` module namespace. */
+export type PdfJsModule = typeof PdfJsNamespace;
+/**
+ * Global PDF.js configuration. Every field is optional; unset asset URLs default to the jsDelivr
+ * CDN copy of the **exact installed** `pdfjs-dist` version. Self-hosting is recommended for
+ * production (see the README).
+ */
+export interface PdfJsConfig {
+    /**
+     * Returns the `pdfjs-dist` module. Use it to select the legacy build
+     * (`() => import('pdfjs-dist/legacy/build/pdf.mjs')`) or a pre-loaded instance.
+     *
+     * @defaultValue `() => import('pdfjs-dist')`
+     */
+    loader?: () => Promise<PdfJsModule>;
+    /**
+     * Worker script URL (e.g. from `import workerSrc from 'pdfjs-dist/build/pdf.worker.min.mjs?url'`).
+     * A worker already set on `GlobalWorkerOptions` is respected.
+     *
+     * @defaultValue the jsDelivr worker for the installed version
+     */
+    workerSrc?: string;
+    /** A ready `Worker` running the PDF.js worker script. Takes precedence over `workerSrc`. */
+    workerPort?: Worker;
+    /**
+     * Base URL of the CMap files, with a trailing slash.
+     *
+     * @defaultValue jsDelivr `cmaps/` for the installed version
+     */
+    cMapUrl?: string;
+    /** Whether the CMaps are binary-packed. Default `true`. */
+    cMapPacked?: boolean;
+    /**
+     * Base URL of the standard font data, with a trailing slash.
+     *
+     * @defaultValue jsDelivr `standard_fonts/` for the installed version
+     */
+    standardFontDataUrl?: string;
+    /**
+     * Base URL of the WebAssembly decoders, with a trailing slash.
+     *
+     * @defaultValue jsDelivr `wasm/` for the installed version
+     */
+    wasmUrl?: string;
+    /**
+     * Base URL of the ICC color profiles, with a trailing slash.
+     *
+     * @defaultValue jsDelivr `iccs/` for the installed version
+     */
+    iccUrl?: string;
+    /**
+     * Forwarded to `getDocument` for builds that still support it. Default `false` (defense in depth
+     * against CVE-2024-4367; `pdfjs-dist` 5+ removed eval-based font compilation entirely).
+     */
+    isEvalSupported?: boolean;
+}
+/**
+ * Configures PDF.js for every viewer instance. Call it once at startup, before the first viewer
+ * mounts. Calls merge with previous configuration.
+ *
+ * @example
+ * ```ts
+ * import workerSrc from 'pdfjs-dist/build/pdf.worker.min.mjs?url';
+ * configurePdfJs({ workerSrc, cMapUrl: '/pdfjs/cmaps/', standardFontDataUrl: '/pdfjs/standard_fonts/' });
+ * ```
+ */
+export declare function configurePdfJs(next: PdfJsConfig): void;
+/** Resets configuration and the cached module. Test-only; not part of the public API. */
+export declare function resetPdfJs(): void;
+/**
+ * Loads `pdfjs-dist` once and shares the result between all instances. A failed load is not
+ * cached, so a later call (e.g. `reload()`) retries. Rejects with a `PDFJS_LOAD_FAILED` error.
+ */
+export declare function loadPdfJs(): Promise<PdfJsModule>;
+/** `getDocument` options every load receives: asset URLs and security defaults. */
+export declare function getDocumentDefaults(lib: PdfJsModule): PdfJsDocumentOptions & {
+    isEvalSupported: boolean;
+};

package/dist/core/print.d.ts

@@ -0,0 +1,16 @@
+import { PDFDocumentProxy } from 'pdfjs-dist';
+/** Options for {@link printDocument}. */
+export interface PrintOptions {
+    /** Aborts page preparation (the print dialog itself cannot be canceled). */
+    signal?: AbortSignal | undefined;
+    /** Called after each prepared page. */
+    onProgress?: ((done: number, total: number) => void) | undefined;
+    /** Render scale; default {@link PRINT_SCALE}. */
+    scale?: number | undefined;
+}
+/**
+ * Prints a document without leaving the page: every page is rendered to an image at print
+ * resolution inside a hidden iframe (one page per sheet, no margins), then the iframe's print
+ * dialog opens. The iframe is removed after printing.
+ */
+export declare function printDocument(pdf: PDFDocumentProxy, { signal, onProgress, scale }?: PrintOptions): Promise<void>;

package/dist/core/scale.d.ts

@@ -0,0 +1,26 @@
+/** Default zoom floor (25%). */
+export declare const DEFAULT_MIN_SCALE = 0.25;
+/** Default zoom ceiling (500%). */
+export declare const DEFAULT_MAX_SCALE = 5;
+/** Default zoom increment (5%). */
+export declare const DEFAULT_SCALE_STEP = 0.05;
+/** 100%: one PDF point per CSS pixel. */
+export declare const DEFAULT_SCALE = 1;
+/** Removes floating-point noise (`1.5000000000000004` → `1.5`). */
+export declare function roundScale(scale: number): number;
+/** Tolerance-based scale comparison. */
+export declare function scalesEqual(a: number, b: number): boolean;
+/** Zoom constraints shared by the buttons, shortcuts and imperative API. */
+export interface ZoomOptions {
+    minScale: number;
+    maxScale: number;
+    scaleStep: number;
+    /** Preset ladder; when non-empty the zoom buttons step between presets instead of by `scaleStep`. */
+    zoomLevels?: readonly number[] | undefined;
+}
+/** The next zoom value in `direction`, or `null` when already at the bound. */
+export declare function nextScale(current: number, direction: 1 | -1, options: ZoomOptions): number | null;
+/** Normalizes an arbitrary requested scale: clamps to the bounds and removes float noise. */
+export declare function normalizeScale(scale: number, options: Pick<ZoomOptions, 'minScale' | 'maxScale'>): number;
+/** Integer percentage shown in the zoom label (`Math.round(scale * 100)`). */
+export declare function scaleToPercent(scale: number): number;

package/dist/core/search.d.ts

@@ -0,0 +1,36 @@
+/** A text item as returned by `getTextContent()` (marked-content entries have no `str`). */
+export interface TextItemLike {
+    str: string;
+    hasEOL?: boolean;
+}
+/** Text of one page prepared for searching. Offsets stay aligned with the text layer's items. */
+export interface PageText {
+    /** All items joined; an end-of-line item is followed by a space. */
+    text: string;
+    /** Lower-cased `text` with identical offsets (falls back to `text` if lower-casing changes length). */
+    folded: string;
+    /** Start offset of each item within `text`. */
+    offsets: number[];
+    /** Text of each item, in text-layer order. */
+    items: string[];
+}
+/** A match within a page's `text`. */
+export interface TextRange {
+    start: number;
+    end: number;
+}
+/** The part of one text item covered by a match. */
+export interface ItemSegment {
+    item: number;
+    start: number;
+    end: number;
+}
+/** Keeps only real text items (the entries the text layer renders as spans). */
+export declare function isTextItem<T>(item: T): item is T & TextItemLike;
+export declare function buildPageText(items: readonly TextItemLike[]): PageText;
+/** Normalizes a query: trimmed, whitespace collapsed, lower-cased. */
+export declare function normalizeQuery(query: string): string;
+/** Non-overlapping, case-insensitive matches of `query` in a page. */
+export declare function findMatches(page: PageText, query: string): TextRange[];
+/** Splits a page-level range into the per-item pieces the text layer can highlight. */
+export declare function toItemSegments(page: PageText, range: TextRange): ItemSegment[];

package/dist/hooks/useControllableState.d.ts

@@ -0,0 +1,19 @@
+/** Options for {@link useControllableState}. */
+export interface UseControllableStateOptions<T> {
+    /** The controlled value. `undefined` means uncontrolled. */
+    value: T | undefined;
+    /** Initial value while uncontrolled. */
+    defaultValue: T | (() => T);
+    /** Called with every change, in both controlled and uncontrolled mode. */
+    onChange?: ((value: T) => void) | undefined;
+    /** Prop name used in development warnings. */
+    name?: string | undefined;
+}
+/** Setter returned by {@link useControllableState}; accepts a value or an updater function. */
+export type SetControllableState<T> = (next: T | ((previous: T) => T)) => void;
+/**
+ * The value / defaultValue / onValueChange pattern. Internal state is used while `value` is
+ * `undefined`; `onChange` fires whenever the value changes. The setter is stable. Values must not
+ * be functions (a function argument is treated as an updater).
+ */
+export declare function useControllableState<T>({ value, defaultValue, onChange, name, }: UseControllableStateOptions<T>): readonly [T, SetControllableState<T>];

package/dist/hooks/useDevicePixelRatio.d.ts

@@ -0,0 +1,2 @@
+/** Current `devicePixelRatio`, updated when the window moves between screens or zooms. */
+export declare function useDevicePixelRatio(): number;

package/dist/hooks/useDocumentSearch.d.ts

@@ -0,0 +1,13 @@
+import { PDFDocumentProxy } from 'pdfjs-dist';
+/** One search hit: its page and its index among that page's matches. */
+export interface SearchMatch {
+    page: number;
+    index: number;
+}
+/**
+ * Finds every match of `query` in the document, page by page (debounced; results stream in).
+ */
+export declare function useDocumentSearch(pdf: PDFDocumentProxy | null, query: string): {
+    matches: SearchMatch[];
+    searching: boolean;
+};

package/dist/hooks/useElementSize.d.ts

@@ -0,0 +1,13 @@
+/** Content-box size of an element, in CSS pixels. */
+export interface ElementSize {
+    width: number;
+    height: number;
+}
+/**
+ * Tracks an element's content-box size with `ResizeObserver`. Returns a callback ref and the
+ * size, which is `null` until the first measurement (and always on the server).
+ */
+export declare function useElementSize<T extends Element>(): [
+    (node: T | null) => void,
+    ElementSize | null
+];

package/dist/hooks/useFullscreen.d.ts

@@ -0,0 +1,18 @@
+import { FullscreenMode } from '../types.js';
+/** How fullscreen is currently presented. */
+export type FullscreenPresentation = 'none' | 'layout' | 'native' | 'overlay';
+interface UseFullscreenOptions {
+    mode: FullscreenMode;
+    active: boolean;
+    setActive: (active: boolean) => void;
+    element: HTMLElement | null;
+}
+/**
+ * Presents fullscreen:
+ * - `controlled`: layout only, the parent decides.
+ * - `native`: the Fullscreen API on `element`; leaving it (e.g. with `Esc`) reports `false`.
+ *   Falls back to `overlay` where element fullscreen is unavailable or refused.
+ * - `overlay`: fixed full-viewport layer with a focus trap, scroll lock and `Esc` to close.
+ */
+export declare function useFullscreen({ mode, active, setActive, element, }: UseFullscreenOptions): FullscreenPresentation;
+export {};

package/dist/hooks/useIsomorphicLayoutEffect.d.ts

@@ -0,0 +1,3 @@
+import { useEffect } from 'react';
+/** `useLayoutEffect` in the browser, `useEffect` on the server (avoids the SSR warning). */
+export declare const useIsomorphicLayoutEffect: typeof useEffect;

package/dist/hooks/useKeyboardShortcuts.d.ts

@@ -0,0 +1,18 @@
+import { PdfViewerApi } from '../types.js';
+type Shortcut = 'previousPage' | 'nextPage' | 'firstPage' | 'lastPage' | 'zoomIn' | 'zoomOut' | 'resetZoom' | 'rotateCw' | 'rotateCcw' | 'toggleFullscreen';
+/** Maps a key press to a viewer shortcut, or `null`. Exported for tests. */
+export declare function getShortcut(event: KeyboardEvent, viewport: HTMLElement | null): Shortcut | null;
+interface UseKeyboardShortcutsOptions {
+    enabled: boolean;
+    /** Shortcuts are active only while focus is inside this element. */
+    element: HTMLElement | null;
+    viewport: HTMLElement | null;
+    api: PdfViewerApi;
+}
+/**
+ * Viewer keyboard shortcuts (active while focus is inside the viewer): ←/→ and PageUp/PageDown
+ * change pages, Home/End jump to the first/last page, `+`/`-` zoom, `0` resets zoom, `r`/`R`
+ * rotate, `f` toggles fullscreen.
+ */
+export declare function useKeyboardShortcuts({ enabled, element, viewport, api, }: UseKeyboardShortcutsOptions): void;
+export {};

package/dist/hooks/useMediaQuery.d.ts

@@ -0,0 +1,2 @@
+/** Whether `query` matches. `false` on the server and where `matchMedia` is unavailable. */
+export declare function useMediaQuery(query: string): boolean;

package/dist/hooks/usePageRenderer.d.ts

@@ -0,0 +1,74 @@
+import { Ref } from 'react';
+import { PDFDocumentProxy } from 'pdfjs-dist';
+import { FitOptions } from '../core/geometry.js';
+import { PdfViewerError, Rotation } from '../types.js';
+/** Details of a completed page render. */
+export interface PageRenderInfo {
+    /** 1-based page number that was rendered (after clamping). */
+    page: number;
+    /** Scale actually rendered (after fitting). */
+    scale: number;
+    /** Rendered CSS width in pixels. */
+    width: number;
+    /** Rendered CSS height in pixels. */
+    height: number;
+    /** Time from request to completion. */
+    durationMs: number;
+}
+/** Search highlighting for one page's text layer. */
+export interface PageHighlight {
+    /** Text to highlight (case-insensitive). */
+    query: string;
+    /** Index of the page's match to mark as selected, if any. */
+    selected: number | null;
+}
+/** Options for {@link usePageRenderer}. */
+export interface UsePageRendererOptions {
+    document: PDFDocumentProxy | null;
+    /** 1-based page number; clamped to the document. */
+    page: number;
+    /** Requested scale (1 = 100%). */
+    scale: number;
+    /** User rotation, added to the page's intrinsic rotation. */
+    rotation: Rotation;
+    /** Optional box the page must fit into. */
+    fit?: FitOptions | undefined;
+    /** Canvas pixel budget. Default {@link DEFAULT_MAX_CANVAS_PIXELS}. */
+    maxCanvasPixels?: number | undefined;
+    /** Render a selectable text layer. */
+    textLayer?: boolean | undefined;
+    /** Render link annotations. */
+    annotationLayer?: boolean | undefined;
+    /** Highlight search matches in the text layer. */
+    highlight?: PageHighlight | undefined;
+    /** Called when an internal link targets a page. */
+    onLinkNavigate?: ((page: number) => void) | undefined;
+    /** Called with the selected highlight element, so it can be scrolled into view. */
+    onHighlight?: ((element: HTMLElement) => void) | undefined;
+    onRender?: ((info: PageRenderInfo) => void) | undefined;
+    onError?: ((error: PdfViewerError) => void) | undefined;
+}
+/** Refs to attach and render state returned by {@link usePageRenderer}. */
+export interface UsePageRendererResult {
+    /** The page box; the renderer sets its CSS width and height. */
+    pageRef: Ref<HTMLDivElement>;
+    /** Element that receives the canvas. Must have no React children. */
+    canvasHostRef: Ref<HTMLDivElement>;
+    /** Element that receives the text and annotation layers. Must have no React children. */
+    layersRef: Ref<HTMLDivElement>;
+    /** The last render failure, cleared by the next successful render. */
+    error: PdfViewerError | null;
+    /** Renders again after a failure. */
+    retry: () => void;
+}
+/**
+ * Renders one PDF page onto a canvas, optionally with text and annotation layers.
+ *
+ * - One render at a time: a newer request cancels the running `RenderTask` (cancellations are
+ *   silent), so bursts of changes complete exactly one render.
+ * - Double-buffered: the canvas and its layers are built off-screen and swapped in together, so
+ *   there is no blank frame.
+ * - HiDPI output, capped at `maxCanvasPixels`; re-renders when the device pixel ratio changes.
+ * - The renderer is the single owner of the page's CSS size.
+ */
+export declare function usePageRenderer({ document, page, scale, rotation, fit, maxCanvasPixels, textLayer, annotationLayer, highlight, onLinkNavigate, onHighlight, onRender, onError, }: UsePageRendererOptions): UsePageRendererResult;

package/dist/hooks/usePdfDocument.d.ts

@@ -0,0 +1,31 @@
+import { PDFDocumentProxy } from 'pdfjs-dist';
+import { PdfDocumentStatus, PdfJsDocumentOptions, PdfRequestOptions, PdfSource, PdfViewerError } from '../types.js';
+/** Options for {@link usePdfDocument}. Changes apply on the next load, except `password`. */
+export interface UsePdfDocumentOptions extends PdfRequestOptions {
+    /** Password for encrypted documents. Changing it reloads the document. */
+    password?: string | undefined;
+    /** Per-instance `getDocument` overrides. */
+    pdfjsOptions?: PdfJsDocumentOptions | undefined;
+    /** Called once the document is ready. */
+    onLoad?: ((document: PDFDocumentProxy) => void) | undefined;
+    /** Called for every load failure except aborts and handled HTTP errors. */
+    onError?: ((error: PdfViewerError) => void) | undefined;
+}
+/** State returned by {@link usePdfDocument}. */
+export interface UsePdfDocumentResult {
+    /** `idle` (no source, or HTTP error handled by the host), `loading`, `ready` or `error`. */
+    status: PdfDocumentStatus;
+    /** The loaded document while `status === 'ready'`. Never a destroyed document. */
+    document: PDFDocumentProxy | null;
+    /** Page count, `0` without a document. */
+    numPages: number;
+    /** The failure while `status === 'error'`. */
+    error: PdfViewerError | null;
+    /** Loads the current source again (e.g. after an error). */
+    reload: () => void;
+}
+/**
+ * Loads a PDF document. Every source change aborts the previous fetch, discards its result and
+ * destroys the previous document; unmounting does the same.
+ */
+export declare function usePdfDocument(source: PdfSource | null | undefined, options?: UsePdfDocumentOptions): UsePdfDocumentResult;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { PdfViewer } from './PdfViewer.js';
+export { PdfToolbar, type PdfToolbarProps } from './components/Toolbar.js';
+export { PdfPageCanvas, type PdfPageCanvasProps } from './components/PdfPageCanvas.js';
+export { configurePdfJs, type PdfJsConfig, type PdfJsModule } from './core/pdfjs.js';
+export type { FitOptions } from './core/geometry.js';
+export { defaultLabels, type LabelContext, type PdfViewerLabels } from './labels.js';
+export { usePdfDocument, type UsePdfDocumentOptions, type UsePdfDocumentResult, } from './hooks/usePdfDocument.js';
+export type { PageHighlight, PageRenderInfo } from './hooks/usePageRenderer.js';
+export { useControllableState, type SetControllableState, type UseControllableStateOptions, } from './hooks/useControllableState.js';
+export type { FullscreenMode, PdfDocumentStatus, PdfJsDocumentOptions, PdfRequestOptions, PdfSource, PdfViewerApi, PdfViewerError, PdfViewerErrorCode, PdfViewerProps, Rotation, ToolbarAction, ToolbarConfig, } from './types.js';