Helpers

Standalone functions the package exports beside the classes. Three draw the document states before and around a document, in place rather than as a browser prompt or a status line: a drop target before any file is chosen, a password prompt, and a load-error card. They take the viewer's locale and toolbar.icons as options.locale and options.icons, so a card shown before the viewer exists speaks its language and draws its icons. createPasswordPrompt and createLoadError return { element, destroy() }; createDropZone returns { element, open(), destroy() }.

Four are geometry helpers for callers that think in edges or quads. Every point and rectangle the API takes or gives is in page space: PDF points (1/72 inch), the origin at the page's bottom-left corner, y growing upwards — the page's own coordinates, as the file holds them and every reader shares them, unturned by the page's rotation. Point is { x, y }, Size is { width, height }, Rect is both (its bottom-left corner and its size; width and height never negative), Quad is { topLeft, topRight, bottomLeft, bottomRight } (one line a text mark covers, its corners named as Acrobat writes them) and RectEdges is { left, bottom, right, top } (how a PDF file stores a rectangle). An annotation's rect, a form field's, a text block's bounds, a search match's rects and a page's boxes are all Rects; a text mark's lines are Quads. A rect given to the API is checked: four finite numbers, width and height not negative, or INVALID_ARGUMENT. To convert between page space and the viewer's CSS pixels, use viewer.pageToClient and viewer.clientToPage.

namespaceimport { createDropZone, createPasswordPrompt, createLoadError, rectFromEdges, rectEdges, quadToRect, rectToQuad } from '@kernstra/pdf-web-sdk'

Usage

TypeScript

import { createDropZone } from '@kernstra/pdf-web-sdk';

const zone = createDropZone(container, {
  onFile: (file) => {
    void openPdf(file);
  }, // a dropped or chosen PDF
  onReject: (file) => {
    /* not a PDF */
  }, // optional
  title: 'Drop a PDF here', // optional
  note: 'Everything happens in this browser. Nothing is uploaded.', // optional
  action: 'Choose a file', // optional
  locale: { lang: 'de', translations: { de: myGerman } }, // optional: the viewer's locale
  icons: { dropZoneFile: myFileIconSvg }, // optional: the viewer's toolbar.icons
});

zone.open(); // opens the file picker — wire it to Ctrl+O
zone.destroy(); // once a document is open

Document states

createDropZonestatic methodsince 1.0.0

createDropZone(container: HTMLElement, options: DropZoneOptions): DropZone

The viewer before a document. A host mounts the viewer and, until a file arrives, has nothing to show but a blank box; this is that box — a drop target, a file picker, and the privacy line.

Parameter	Type	Description
container	HTMLElement	Where the box is mounted — the element the viewer will later use.
options	DropZoneOptions	`{ onFile, onReject?, title?, note?, action?, locale?, icons? }`. `onFile(file)` receives a dropped or chosen PDF; `onReject(file)` a file that is not a PDF. `title`, `note` and `action` are the words shown; `locale` is the viewer's locale and `icons` its toolbar.icons.

Returns DropZone { element, open(), destroy() } — open() opens the file picker, for a host shortcut such as Ctrl+O; destroy() once a document is open.

TypeScript

const zone = createDropZone(container, { onFile: (file) => void openPdf(file) });
window.addEventListener('keydown', (e) => {
  if ((e.metaKey || e.ctrlKey) && e.key === 'o') zone.open();
});

createPasswordPromptstatic methodsince 1.0.0

createPasswordPrompt(container: HTMLElement, options: PasswordPromptOptions): PasswordPrompt

"This document is protected · Enter the password to open it." — shown in place when a load rejects with PASSWORD_ERROR. A wrong password (resolve false from onUnlock) shakes the field and says so.

Parameter	Type	Description
container	HTMLElement	Where the prompt is mounted.
options	PasswordPromptOptions	`{ onUnlock, onCancel?, name?, locale?, icons? }`. `onUnlock(password)` returns `true` / `false` directly or as a promise — `false` shakes the field and says the password was wrong; `onCancel()` when the user gives up; `name` is the file's name to show; `locale` and `icons` as for `createDropZone`.

Returns PasswordPrompt { element, destroy() }.

TypeScript

import { createPasswordPrompt, createLoadError, PDFDocument, SDKError } from '@kernstra/pdf-web-sdk';

try {
  doc = await PDFDocument.fromFile(file);
} catch (err) {
  if (err instanceof SDKError && err.code === 'PASSWORD_ERROR') {
    const prompt = createPasswordPrompt(container, {
      name: file.name,
      onUnlock: async (password) => {
        try {
          doc = await PDFDocument.fromFile(file, { password });
          prompt.destroy();
          return true;
        } catch {
          return false; // shakes the field
        }
      },
    });
  } else {
    createLoadError(container, { error: err, onRetry: () => openPdf(file) });
  }
}

createLoadErrorstatic methodsince 1.0.0

createLoadError(container: HTMLElement, options: LoadErrorOptions): LoadErrorCard

The load-failure card: plain language first ("The PDF appears to be damaged or incomplete."), the SDKError code second and small (the error's own message is its tooltip), then Try another file / Retry.

Parameter	Type	Description
container	HTMLElement	Where the card is mounted.
options	LoadErrorOptions	`{ error, onRetry?, onChooseAnother?, locale?, icons? }`. `error` is what the load rejected with (an `SDKError`, or anything else); `onRetry()` and `onChooseAnother()` back the Retry and Try another file buttons; `locale` and `icons` as for `createDropZone`.

Returns LoadErrorCard { element, destroy() }.

TypeScript

const card = createLoadError(container, {
  error: err,
  onRetry: () => openPdf(file),
  onChooseAnother: () => zone.open(),
});

Geometry

rectFromEdgesstatic methodsince 1.0.0

rectFromEdges(edges: RectEdges): Rect

A Rect from four edges, whichever way round the edges are given.

Parameter	Type	Description
edges	RectEdges	`{ left, bottom, right, top }` — how a PDF file stores a rectangle, whichever way round the edges are given.

Returns Rect Its bottom-left corner and its size.

TypeScript

const rect = rectFromEdges({ left: 72, bottom: 700, right: 300, top: 720 });

rectEdgesstatic methodsince 1.0.0

rectEdges(rect: Rect): RectEdges

The four edges of a Rect, as a PDF file stores them.

Parameter	Type	Description
rect	Rect	A rectangle in page space.

Returns RectEdges { left, bottom, right, top }.

TypeScript

if (annotation.rect) {
  const { left, bottom, right, top } = rectEdges(annotation.rect);
}

quadToRectstatic methodsince 1.0.0

quadToRect(quad: Quad): Rect

A Quad's bounds, as a Rect.

Parameter	Type	Description
quad	Quad	`{ topLeft, topRight, bottomLeft, bottomRight }` — one line a text mark covers.

Returns Rect The bounds of the quad.

TypeScript

const [first] = highlight.quads ?? [];
const firstLine = first ? quadToRect(first) : null;

rectToQuadstatic methodsince 1.0.0

rectToQuad(rect: Rect): Quad

A Rect as a Quad, its corners named as Acrobat writes them.

Parameter	Type	Description
rect	Rect	A rectangle in page space.

Returns Quad Its four corners as { topLeft, topRight, bottomLeft, bottomRight }.

TypeScript

const [first] = match.rects;
const quad = first ? rectToQuad(first) : null;