# 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](https://kernstra.com/docs/web-sdk/config/locale) and [toolbar.icons](https://kernstra.com/docs/web-sdk/config/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 `Rect`s; a text mark's lines are `Quad`s. 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](https://kernstra.com/docs/web-sdk/api/pdfviewer/pagetoclient) and [viewer.clientToPage](https://kernstra.com/docs/web-sdk/api/pdfviewer/clienttopage).

- Kind: namespace
- Access: `import { createDropZone, createPasswordPrompt, createLoadError, rectFromEdges, rectEdges, quadToRect, rectToQuad } from '@kernstra/pdf-web-sdk'`

## Usage

```ts
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

### `createDropZone`

```ts
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.

- Kind: static method
- Since: 1.0.0

| 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](https://kernstra.com/docs/web-sdk/config/locale) and `icons` its [toolbar.icons](https://kernstra.com/docs/web-sdk/config/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.

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

Page: https://kernstra.com/docs/web-sdk/api/helpers/createdropzone

### `createPasswordPrompt`

```ts
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.

- Kind: static method
- Since: 1.0.0

| 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() }`.

```ts
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) });
  }
}
```

Page: https://kernstra.com/docs/web-sdk/api/helpers/createpasswordprompt

### `createLoadError`

```ts
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**.

- Kind: static method
- Since: 1.0.0

| 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() }`.

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

Page: https://kernstra.com/docs/web-sdk/api/helpers/createloaderror

## Geometry

### `rectFromEdges`

```ts
rectFromEdges(edges: RectEdges): Rect
```

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

- Kind: static method
- Since: 1.0.0

| 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.

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

Page: https://kernstra.com/docs/web-sdk/api/helpers/rectfromedges

### `rectEdges`

```ts
rectEdges(rect: Rect): RectEdges
```

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

- Kind: static method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `rect` | `Rect` | A rectangle in page space. |

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

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

Page: https://kernstra.com/docs/web-sdk/api/helpers/rectedges

### `quadToRect`

```ts
quadToRect(quad: Quad): Rect
```

A `Quad`'s bounds, as a `Rect`.

- Kind: static method
- Since: 1.0.0

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

Returns `Rect`: The bounds of the quad.

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

Page: https://kernstra.com/docs/web-sdk/api/helpers/quadtorect

### `rectToQuad`

```ts
rectToQuad(rect: Rect): Quad
```

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

- Kind: static method
- Since: 1.0.0

| Parameter | Type | Description |
| --- | --- | --- |
| `rect` | `Rect` | A rectangle in page space. |

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

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

Page: https://kernstra.com/docs/web-sdk/api/helpers/recttoquad

Web page: https://kernstra.com/docs/web-sdk/api/helpers