@unlev/exeq 0.3.1 → 0.3.2

package/README.md

@@ -148,13 +148,113 @@ import { renderPdfPages, generateFilledPdf, downloadPdf } from '@unlev/exeq';
 // Render PDF pages to images
 const pages = await renderPdfPages(pdfUrlOrBytes);
 
-// Generate a filled PDF with form values overlaid
-const bytes = await generateFilledPdf(pdfSource, fields);
+// Generate a filled PDF
+const bytes = await generateFilledPdf({ pdfSource, fields });
 
 // Trigger browser download
 downloadPdf(bytes, 'signed-document.pdf');
 ```
 
+### `generateFilledPdf`
+
+```ts
+generateFilledPdf(opts: FillPdfOptions): Promise<Uint8Array>
+```
+
+```ts
+import { generateFilledPdf, US_LETTER } from '@unlev/exeq';
+
+// Overlay-only: blank Letter pages with no background — for printing
+// onto pre-printed physical forms.
+const overlay = await generateFilledPdf({
+  pdfSource: null,
+  fields,
+  pageSize: US_LETTER,
+});
+
+// Always-Letter output even when the source PDF isn't Letter — useful
+// when the source is a scan at slightly different dimensions.
+const letter = await generateFilledPdf({
+  pdfSource: '/forms/template.pdf',
+  fields,
+  pageSize: US_LETTER,
+});
+
+// Resolve formula fields during render.
+const filled = await generateFilledPdf({
+  pdfSource,
+  fields,
+  resolveFormulas: true,
+  customTransforms: { last4: v => v.slice(-4) },
+});
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `pdfSource` | `string \| ArrayBuffer \| null` | Background PDF (URL or bytes), or `null` for overlay-only output. |
+| `fields` | `FormField[]` | Fields to render on top of the background. |
+| `pageSize` | `[number, number]` | Override output page size in PDF points (72pt = 1in). With a source, source pages are drawn stretched to fit. Defaults to source dims, or Letter if no source. |
+| `pageCount` | `number` | When `pdfSource` is null, how many blank pages to render. Default `1`. |
+| `resolveFormulas` | `boolean` | Run `resolveAllFormulas` on fields before rendering. Default `false`. |
+| `customTransforms` | `TransformMap` | Merged with `BUILTIN_TRANSFORMS` during formula resolution. |
+| `calibration` | `Calibration` | Linear offset/scale applied to field positions. |
+
+### `createPdfBuilder` — batch / mail merge
+
+For multi-record output (e.g. one PDF with one page per recipient), `createPdfBuilder` merges records into a single document and dedupes shared resources — the source PDF, fonts, and signature PNGs are embedded once and referenced from every page.
+
+```ts
+import { createPdfBuilder, downloadPdf, US_LETTER } from '@unlev/exeq';
+
+const builder = await createPdfBuilder({ pageSize: US_LETTER });
+for (const record of records) {
+  await builder.addRecord({
+    pdfSource: '/forms/template.pdf',  // embedded once, referenced N times
+    fields: record.fields,
+    resolveFormulas: true,
+  });
+}
+const bytes = await builder.save();
+downloadPdf(bytes, 'merged.pdf');
+```
+
+A 12-record batch with a 700 KB background goes from ~8 MB (12 separate `generateFilledPdf` calls, then merged with `pdf-lib`) to ~705 KB (one embed shared across pages).
+
+`PdfBuilder.doc` exposes the underlying `pdf-lib` document if you need to add an audit trail or table-of-contents page before saving.
+
+### Calibration
+
+When a printed overlay doesn't quite register with a pre-printed physical form (because the scan was cropped differently than the real paper, or the printer tray has a small offset), apply a linear calibration. Offsets are in PDF points (72pt = 1 inch).
+
+```ts
+import { applyCalibration, generateFilledPdf, US_LETTER } from '@unlev/exeq';
+
+// Either pass calibration to the renderer:
+const bytes = await generateFilledPdf(pdfSource, fields, {
+  pageSize: US_LETTER,
+  calibration: { xOffset: -5, yOffset: 3, xScale: 1.005, yScale: 1 },
+});
+
+// …or apply it as a standalone transform (useful for previews):
+const adjusted = applyCalibration(fields, { xOffset: -5, yOffset: 3, xScale: 1.005, yScale: 1 });
+```
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `xOffset` | `number` (pt) | Horizontal shift; positive = right. |
+| `yOffset` | `number` (pt) | Vertical shift; positive = down (screen coords). |
+| `xScale` | `number` | Multiplier on x and width. |
+| `yScale` | `number` | Multiplier on y and height. |
+
+### Page-size constants
+
+```ts
+import { US_LETTER, US_LEGAL, A4 } from '@unlev/exeq';
+// US_LETTER === [612, 792]
+// US_LEGAL  === [612, 1008]
+// A4        === [595.28, 841.89]
+```
+
 ### Types
 
 ```ts

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { PDFDocument } from 'pdf-lib';
 
 declare function generateId(): string;
 type FieldType = 'text' | 'dropdown' | 'signature' | 'signed-date' | 'checkbox' | 'initials' | 'blackout' | 'whiteout';
@@ -27,6 +28,7 @@ interface FormField {
     options?: string[];
     formula?: string;
     locked?: boolean;
+    autoShrink?: boolean;
 }
 interface Template {
     fields: FormField[];
@@ -193,8 +195,120 @@ interface SignerRoleSelectorProps {
 }
 declare function SignerRoleSelector({ roles, activeRole, onSetActiveRole, onAddRole, onRemoveRole, }: SignerRoleSelectorProps): react_jsx_runtime.JSX.Element;
 
-declare function generateFilledPdf(pdfSource: string | ArrayBuffer, fields: FormField[]): Promise<Uint8Array>;
+/** US Letter in PDF points (72pt = 1 in). */
+declare const US_LETTER: [number, number];
+/** US Legal in PDF points. */
+declare const US_LEGAL: [number, number];
+/** A4 in PDF points. */
+declare const A4: [number, number];
+/**
+ * Linear calibration applied to every field's percentage position and size.
+ * Use to align rendered output with a physical pre-printed form when the
+ * template's source PDF and the real paper don't exactly agree on crop or
+ * scale.
+ *
+ * Math (for an output page of size [pW, pH] pt):
+ *   xPctOff = (xOffset / pW) * 100
+ *   yPctOff = (yOffset / pH) * 100
+ *   x' = x_pct * xScale + xPctOff
+ *   y' = y_pct * yScale + yPctOff
+ *   width'  = width_pct  * xScale
+ *   height' = height_pct * yScale
+ *
+ * Defaults (scale=1, offsets=0) are a no-op.
+ */
+interface Calibration {
+    /** Horizontal offset in PDF points; positive = right. */
+    xOffset: number;
+    /** Vertical offset in PDF points; positive = down (screen coords). */
+    yOffset: number;
+    /** Horizontal multiplier applied to x and width. */
+    xScale: number;
+    /** Vertical multiplier applied to y and height. */
+    yScale: number;
+}
+declare const DEFAULT_CALIBRATION: Calibration;
+/**
+ * Returns a copy of `fields` with calibration applied to x / y / width /
+ * height. The math is page-size-aware so an `xOffset` of 5pt actually
+ * shifts the rendered output 5pt to the right.
+ *
+ * @param pageSize Output page size in pt used to convert pt offsets to
+ *   percent offsets. Defaults to US Letter.
+ */
+declare function applyCalibration(fields: FormField[], calibration: Calibration, pageSize?: [number, number]): FormField[];
+interface FillPdfOptions {
+    /** Source PDF used as the background.
+     *  - `string` (URL): fetched, embedded once per URL across the document.
+     *  - `ArrayBuffer`: embedded uniquely each call.
+     *  - `null`: render onto blank pages (overlay-only output). */
+    pdfSource: string | ArrayBuffer | null;
+    /** Fields to render on top of the background. */
+    fields: FormField[];
+    /** Override the output page size in PDF points.
+     *  - With a `pdfSource`, source pages are drawn stretched to fit.
+     *  - With `pdfSource: null`, blank pages of this size are created.
+     *  - When omitted with a source, output uses the source's page sizes.
+     *  - When omitted with `pdfSource: null`, defaults to US Letter. */
+    pageSize?: [number, number];
+    /** When `pdfSource` is null, how many blank pages to render. Default `1`.
+     * Fields with out-of-range `page` indices are skipped. */
+    pageCount?: number;
+    /** Run `resolveAllFormulas` on fields before rendering. */
+    resolveFormulas?: boolean;
+    /** Custom transforms merged with `BUILTIN_TRANSFORMS` during formula
+     * resolution. Only meaningful when `resolveFormulas` is true. */
+    customTransforms?: TransformMap;
+    /** Linear calibration applied to field positions before rendering. */
+    calibration?: Calibration;
+}
+/**
+ * Generates one filled PDF.
+ *
+ *   const bytes = await generateFilledPdf({
+ *     pdfSource: '/forms/template.pdf',
+ *     fields: template.fields,
+ *     pageSize: US_LETTER,
+ *     resolveFormulas: true,
+ *   });
+ *
+ * For multi-record output that shares a background, use `createPdfBuilder`
+ * — it dedupes the embedded source across all pages.
+ */
+declare function generateFilledPdf(opts: FillPdfOptions): Promise<Uint8Array>;
+interface PdfBuilder {
+    /** Underlying pdf-lib document — exposed for advanced post-processing
+     * (audit-trail pages, custom metadata, etc.). */
+    readonly doc: PDFDocument;
+    /** Append one record's pages to the output. */
+    addRecord(opts: FillPdfOptions): Promise<void>;
+    /** Finalize and return the merged PDF bytes. */
+    save(): Promise<Uint8Array>;
+}
+interface CreatePdfBuilderOptions {
+    /** Default `pageSize` for any `addRecord` call that doesn't set its own. */
+    pageSize?: [number, number];
+}
+/**
+ * Creates a builder that merges multiple filled records into one PDF.
+ *
+ * Resources (source PDFs indexed by URL, embedded fonts, signature PNGs) are
+ * embedded once across the whole document and reused — critical for
+ * mail-merge style batches where dozens of records share the same background.
+ *
+ *   const builder = await createPdfBuilder({ pageSize: US_LETTER });
+ *   for (const record of records) {
+ *     await builder.addRecord({
+ *       pdfSource: '/forms/template.pdf',
+ *       fields: record.fields,
+ *       resolveFormulas: true,
+ *     });
+ *   }
+ *   const bytes = await builder.save();
+ *   downloadPdf(bytes, 'merged.pdf');
+ */
+declare function createPdfBuilder(defaults?: CreatePdfBuilderOptions): Promise<PdfBuilder>;
 declare function downloadPdf(bytes: Uint8Array, filename: string): void;
 declare function postPdfToCallback(bytes: Uint8Array, callbackUrl: string, filename: string): Promise<void>;
 
-export { BUILTIN_TRANSFORMS, DEFAULT_SIGNER_ROLES, DesignerView, type DesignerViewProps, FIELD_DEFAULTS, FONT_FAMILIES, FieldNavigator, FieldPropertyPanel, type FieldType, type FormField, PdfViewer, type RenderedPage, SIGNER_ROLE_COLORS, SignatureCanvas, SignerRoleSelector, SignerView, type SignerViewProps, type Template, type TextSubtype, type TransformFn, type TransformMap, createField, downloadPdf, generateFilledPdf, generateId, getSignerColor, postPdfToCallback, renderPdfPages, resolveAllFormulas, resolveFormula, uniqueLabel };
+export { A4, BUILTIN_TRANSFORMS, type Calibration, type CreatePdfBuilderOptions, DEFAULT_CALIBRATION, DEFAULT_SIGNER_ROLES, DesignerView, type DesignerViewProps, FIELD_DEFAULTS, FONT_FAMILIES, FieldNavigator, FieldPropertyPanel, type FieldType, type FillPdfOptions, type FormField, type PdfBuilder, PdfViewer, type RenderedPage, SIGNER_ROLE_COLORS, SignatureCanvas, SignerRoleSelector, SignerView, type SignerViewProps, type Template, type TextSubtype, type TransformFn, type TransformMap, US_LEGAL, US_LETTER, applyCalibration, createField, createPdfBuilder, downloadPdf, generateFilledPdf, generateId, getSignerColor, postPdfToCallback, renderPdfPages, resolveAllFormulas, resolveFormula, uniqueLabel };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { PDFDocument } from 'pdf-lib';
 
 declare function generateId(): string;
 type FieldType = 'text' | 'dropdown' | 'signature' | 'signed-date' | 'checkbox' | 'initials' | 'blackout' | 'whiteout';
@@ -27,6 +28,7 @@ interface FormField {
     options?: string[];
     formula?: string;
     locked?: boolean;
+    autoShrink?: boolean;
 }
 interface Template {
     fields: FormField[];
@@ -193,8 +195,120 @@ interface SignerRoleSelectorProps {
 }
 declare function SignerRoleSelector({ roles, activeRole, onSetActiveRole, onAddRole, onRemoveRole, }: SignerRoleSelectorProps): react_jsx_runtime.JSX.Element;
 
-declare function generateFilledPdf(pdfSource: string | ArrayBuffer, fields: FormField[]): Promise<Uint8Array>;
+/** US Letter in PDF points (72pt = 1 in). */
+declare const US_LETTER: [number, number];
+/** US Legal in PDF points. */
+declare const US_LEGAL: [number, number];
+/** A4 in PDF points. */
+declare const A4: [number, number];
+/**
+ * Linear calibration applied to every field's percentage position and size.
+ * Use to align rendered output with a physical pre-printed form when the
+ * template's source PDF and the real paper don't exactly agree on crop or
+ * scale.
+ *
+ * Math (for an output page of size [pW, pH] pt):
+ *   xPctOff = (xOffset / pW) * 100
+ *   yPctOff = (yOffset / pH) * 100
+ *   x' = x_pct * xScale + xPctOff
+ *   y' = y_pct * yScale + yPctOff
+ *   width'  = width_pct  * xScale
+ *   height' = height_pct * yScale
+ *
+ * Defaults (scale=1, offsets=0) are a no-op.
+ */
+interface Calibration {
+    /** Horizontal offset in PDF points; positive = right. */
+    xOffset: number;
+    /** Vertical offset in PDF points; positive = down (screen coords). */
+    yOffset: number;
+    /** Horizontal multiplier applied to x and width. */
+    xScale: number;
+    /** Vertical multiplier applied to y and height. */
+    yScale: number;
+}
+declare const DEFAULT_CALIBRATION: Calibration;
+/**
+ * Returns a copy of `fields` with calibration applied to x / y / width /
+ * height. The math is page-size-aware so an `xOffset` of 5pt actually
+ * shifts the rendered output 5pt to the right.
+ *
+ * @param pageSize Output page size in pt used to convert pt offsets to
+ *   percent offsets. Defaults to US Letter.
+ */
+declare function applyCalibration(fields: FormField[], calibration: Calibration, pageSize?: [number, number]): FormField[];
+interface FillPdfOptions {
+    /** Source PDF used as the background.
+     *  - `string` (URL): fetched, embedded once per URL across the document.
+     *  - `ArrayBuffer`: embedded uniquely each call.
+     *  - `null`: render onto blank pages (overlay-only output). */
+    pdfSource: string | ArrayBuffer | null;
+    /** Fields to render on top of the background. */
+    fields: FormField[];
+    /** Override the output page size in PDF points.
+     *  - With a `pdfSource`, source pages are drawn stretched to fit.
+     *  - With `pdfSource: null`, blank pages of this size are created.
+     *  - When omitted with a source, output uses the source's page sizes.
+     *  - When omitted with `pdfSource: null`, defaults to US Letter. */
+    pageSize?: [number, number];
+    /** When `pdfSource` is null, how many blank pages to render. Default `1`.
+     * Fields with out-of-range `page` indices are skipped. */
+    pageCount?: number;
+    /** Run `resolveAllFormulas` on fields before rendering. */
+    resolveFormulas?: boolean;
+    /** Custom transforms merged with `BUILTIN_TRANSFORMS` during formula
+     * resolution. Only meaningful when `resolveFormulas` is true. */
+    customTransforms?: TransformMap;
+    /** Linear calibration applied to field positions before rendering. */
+    calibration?: Calibration;
+}
+/**
+ * Generates one filled PDF.
+ *
+ *   const bytes = await generateFilledPdf({
+ *     pdfSource: '/forms/template.pdf',
+ *     fields: template.fields,
+ *     pageSize: US_LETTER,
+ *     resolveFormulas: true,
+ *   });
+ *
+ * For multi-record output that shares a background, use `createPdfBuilder`
+ * — it dedupes the embedded source across all pages.
+ */
+declare function generateFilledPdf(opts: FillPdfOptions): Promise<Uint8Array>;
+interface PdfBuilder {
+    /** Underlying pdf-lib document — exposed for advanced post-processing
+     * (audit-trail pages, custom metadata, etc.). */
+    readonly doc: PDFDocument;
+    /** Append one record's pages to the output. */
+    addRecord(opts: FillPdfOptions): Promise<void>;
+    /** Finalize and return the merged PDF bytes. */
+    save(): Promise<Uint8Array>;
+}
+interface CreatePdfBuilderOptions {
+    /** Default `pageSize` for any `addRecord` call that doesn't set its own. */
+    pageSize?: [number, number];
+}
+/**
+ * Creates a builder that merges multiple filled records into one PDF.
+ *
+ * Resources (source PDFs indexed by URL, embedded fonts, signature PNGs) are
+ * embedded once across the whole document and reused — critical for
+ * mail-merge style batches where dozens of records share the same background.
+ *
+ *   const builder = await createPdfBuilder({ pageSize: US_LETTER });
+ *   for (const record of records) {
+ *     await builder.addRecord({
+ *       pdfSource: '/forms/template.pdf',
+ *       fields: record.fields,
+ *       resolveFormulas: true,
+ *     });
+ *   }
+ *   const bytes = await builder.save();
+ *   downloadPdf(bytes, 'merged.pdf');
+ */
+declare function createPdfBuilder(defaults?: CreatePdfBuilderOptions): Promise<PdfBuilder>;
 declare function downloadPdf(bytes: Uint8Array, filename: string): void;
 declare function postPdfToCallback(bytes: Uint8Array, callbackUrl: string, filename: string): Promise<void>;
 
-export { BUILTIN_TRANSFORMS, DEFAULT_SIGNER_ROLES, DesignerView, type DesignerViewProps, FIELD_DEFAULTS, FONT_FAMILIES, FieldNavigator, FieldPropertyPanel, type FieldType, type FormField, PdfViewer, type RenderedPage, SIGNER_ROLE_COLORS, SignatureCanvas, SignerRoleSelector, SignerView, type SignerViewProps, type Template, type TextSubtype, type TransformFn, type TransformMap, createField, downloadPdf, generateFilledPdf, generateId, getSignerColor, postPdfToCallback, renderPdfPages, resolveAllFormulas, resolveFormula, uniqueLabel };
+export { A4, BUILTIN_TRANSFORMS, type Calibration, type CreatePdfBuilderOptions, DEFAULT_CALIBRATION, DEFAULT_SIGNER_ROLES, DesignerView, type DesignerViewProps, FIELD_DEFAULTS, FONT_FAMILIES, FieldNavigator, FieldPropertyPanel, type FieldType, type FillPdfOptions, type FormField, type PdfBuilder, PdfViewer, type RenderedPage, SIGNER_ROLE_COLORS, SignatureCanvas, SignerRoleSelector, SignerView, type SignerViewProps, type Template, type TextSubtype, type TransformFn, type TransformMap, US_LEGAL, US_LETTER, applyCalibration, createField, createPdfBuilder, downloadPdf, generateFilledPdf, generateId, getSignerColor, postPdfToCallback, renderPdfPages, resolveAllFormulas, resolveFormula, uniqueLabel };