@unlev/exeq 0.6.0 → 0.6.1

package/dist/pdfFiller-Btf-SnEB.d.mts

@@ -0,0 +1,247 @@
+import { PDFDocument } from 'pdf-lib';
+
+declare function generateId(): string;
+type FieldType = 'text' | 'dropdown' | 'signature' | 'signed-date' | 'checkbox' | 'initials' | 'blackout' | 'whiteout';
+type TextSubtype = 'freeform' | 'number' | 'date' | 'email' | 'phone';
+interface FormField {
+    id: string;
+    type: FieldType;
+    textSubtype?: TextSubtype;
+    label: string;
+    placeholder: string;
+    required: boolean;
+    assignee: string;
+    page: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fontSize: number;
+    value: string;
+    inkColor?: string;
+    letterSpacing?: number;
+    lineHeight?: number;
+    align?: 'left' | 'center' | 'right';
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    fontFamily?: string;
+    options?: string[];
+    formula?: string;
+    locked?: boolean;
+    autoShrink?: boolean;
+}
+interface Template {
+    fields: FormField[];
+    signerRoles: string[];
+    pdfUrl: string;
+}
+declare const DEFAULT_SIGNER_ROLES: string[];
+declare const SIGNER_ROLE_COLORS: Record<string, string>;
+declare function getSignerColor(role: string): string;
+declare function isRedactField(f: FormField | {
+    type: FieldType;
+}): boolean;
+declare function isSignatureField(f: FormField | {
+    type: FieldType;
+}): boolean;
+declare function isTextLikeField(f: FormField | {
+    type: FieldType;
+}): boolean;
+declare function getInputType(subtype?: TextSubtype): string;
+declare function getCssFontFamily(fontFamily?: string): string | undefined;
+declare function sortFieldsByPosition(fields: FormField[]): FormField[];
+declare function preserveFieldValues(oldFields: FormField[], newFields: FormField[]): FormField[];
+declare function getFieldValues(fields: FormField[]): Record<string, string>;
+declare const FONT_FAMILIES: readonly [{
+    readonly value: "Helvetica";
+    readonly label: "Helvetica";
+}, {
+    readonly value: "Courier";
+    readonly label: "Courier New";
+}, {
+    readonly value: "TimesRoman";
+    readonly label: "Times New Roman";
+}];
+declare const FIELD_DEFAULTS: Record<FieldType, Partial<FormField>>;
+/** Given a desired label and a list of existing labels, return a unique label by appending a number if needed. */
+declare function uniqueLabel(desired: string, existingLabels: string[]): string;
+declare function createField(type: FieldType, assignee: string, page: number, x: number, y: number, existingFields?: FormField[]): FormField;
+
+type TransformFn = (value: string) => string;
+type TransformMap = Record<string, TransformFn>;
+/**
+ * Parse a date string robustly into a local Date (midnight, local TZ) so that
+ * getMonth/getDate/getFullYear are calendar-correct. Handles:
+ *  - ISO date-only "YYYY-MM-DD" → parsed as LOCAL (avoids the classic UTC
+ *    off-by-one where "2024-03-15" becomes the 14th in western timezones).
+ *  - Excel serial numbers (a bare integer, e.g. "45000") → converted.
+ *  - Anything else → native `new Date` (handles "M/D/YYYY", ISO datetimes, …).
+ * Returns null when unparseable.
+ */
+declare function parseDate(value: string): Date | null;
+/** Built-in transforms that ship with exeq. */
+declare const BUILTIN_TRANSFORMS: TransformMap;
+/**
+ * Resolve a single formula string against a set of fields and transforms.
+ * Formula format: "{{Source Field Label | transform}}" or "{{Source Field Label}}" (no transform = raw value).
+ * Multiple expressions can appear in one formula: "{{First}} {{Last}}" → "Jane Smith"
+ *
+ * Source resolution order for "{{Name}}":
+ *   1. a placed field whose label (case-insensitive) or id matches Name
+ *   2. `values[Name]` — imported/contextual data not tied to a placed field
+ *   3. the built-in `today` / `now` source (current date)
+ *
+ * @param values Extra named values (e.g. imported CSV/form data) made available
+ *   to formula sources even when there is no placed field for them.
+ */
+declare function resolveFormula(formula: string, fields: FormField[], customTransforms?: TransformMap, values?: Record<string, string>): string;
+/**
+ * Resolve all formula fields in a fields array.
+ * Returns a new array with computed values filled in.
+ *
+ * @param values Extra named values available to formula sources (see resolveFormula).
+ */
+declare function resolveAllFormulas(fields: FormField[], customTransforms?: TransformMap, values?: Record<string, string>): FormField[];
+
+/** 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;
+    /** Extra named values made available to formula sources (e.g. imported CSV/
+     * form data) even when there is no placed field for them. Only meaningful
+     * when `resolveFormulas` is true. */
+    formulaValues?: Record<string, string>;
+    /** 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, builderOptions?: Omit<CreatePdfBuilderOptions, 'pageSize'>): 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>;
+}
+/** Document-level metadata applied at `save()` time. */
+interface PdfMetadata {
+    title?: string;
+    author?: string;
+    subject?: string;
+    creator?: string;
+    producer?: string;
+    /** Document creation date. Pin to a fixed `Date` for reproducible output. */
+    creationDate?: Date;
+    /** Document modification date. Pin to a fixed `Date` for reproducible output. */
+    modificationDate?: Date;
+}
+interface CreatePdfBuilderOptions {
+    /** Default `pageSize` for any `addRecord` call that doesn't set its own. */
+    pageSize?: [number, number];
+    /** Document metadata applied at `save()` time. Pin `creationDate` and
+     *  `modificationDate` to fixed `Date`s for byte-identical output across runs
+     *  — pdf-lib otherwise stamps the current time, so two runs of identical
+     *  input would differ. Useful for server-side generation and caching. */
+    metadata?: PdfMetadata;
+}
+/**
+ * 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 { A4 as A, BUILTIN_TRANSFORMS as B, type Calibration as C, DEFAULT_CALIBRATION as D, preserveFieldValues as E, type FormField as F, resolveAllFormulas as G, resolveFormula as H, sortFieldsByPosition as I, uniqueLabel as J, type PdfBuilder as P, SIGNER_ROLE_COLORS as S, type Template as T, US_LEGAL as U, type TransformMap as a, type FieldType as b, type CreatePdfBuilderOptions as c, DEFAULT_SIGNER_ROLES as d, FIELD_DEFAULTS as e, FONT_FAMILIES as f, type FillPdfOptions as g, type PdfMetadata as h, type TextSubtype as i, type TransformFn as j, US_LETTER as k, applyCalibration as l, createField as m, createPdfBuilder as n, downloadPdf as o, generateFilledPdf as p, generateId as q, getCssFontFamily as r, getFieldValues as s, getInputType as t, getSignerColor as u, isRedactField as v, isSignatureField as w, isTextLikeField as x, parseDate as y, postPdfToCallback as z };

package/dist/pdfFiller-Btf-SnEB.d.ts

@@ -0,0 +1,247 @@
+import { PDFDocument } from 'pdf-lib';
+
+declare function generateId(): string;
+type FieldType = 'text' | 'dropdown' | 'signature' | 'signed-date' | 'checkbox' | 'initials' | 'blackout' | 'whiteout';
+type TextSubtype = 'freeform' | 'number' | 'date' | 'email' | 'phone';
+interface FormField {
+    id: string;
+    type: FieldType;
+    textSubtype?: TextSubtype;
+    label: string;
+    placeholder: string;
+    required: boolean;
+    assignee: string;
+    page: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fontSize: number;
+    value: string;
+    inkColor?: string;
+    letterSpacing?: number;
+    lineHeight?: number;
+    align?: 'left' | 'center' | 'right';
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    fontFamily?: string;
+    options?: string[];
+    formula?: string;
+    locked?: boolean;
+    autoShrink?: boolean;
+}
+interface Template {
+    fields: FormField[];
+    signerRoles: string[];
+    pdfUrl: string;
+}
+declare const DEFAULT_SIGNER_ROLES: string[];
+declare const SIGNER_ROLE_COLORS: Record<string, string>;
+declare function getSignerColor(role: string): string;
+declare function isRedactField(f: FormField | {
+    type: FieldType;
+}): boolean;
+declare function isSignatureField(f: FormField | {
+    type: FieldType;
+}): boolean;
+declare function isTextLikeField(f: FormField | {
+    type: FieldType;
+}): boolean;
+declare function getInputType(subtype?: TextSubtype): string;
+declare function getCssFontFamily(fontFamily?: string): string | undefined;
+declare function sortFieldsByPosition(fields: FormField[]): FormField[];
+declare function preserveFieldValues(oldFields: FormField[], newFields: FormField[]): FormField[];
+declare function getFieldValues(fields: FormField[]): Record<string, string>;
+declare const FONT_FAMILIES: readonly [{
+    readonly value: "Helvetica";
+    readonly label: "Helvetica";
+}, {
+    readonly value: "Courier";
+    readonly label: "Courier New";
+}, {
+    readonly value: "TimesRoman";
+    readonly label: "Times New Roman";
+}];
+declare const FIELD_DEFAULTS: Record<FieldType, Partial<FormField>>;
+/** Given a desired label and a list of existing labels, return a unique label by appending a number if needed. */
+declare function uniqueLabel(desired: string, existingLabels: string[]): string;
+declare function createField(type: FieldType, assignee: string, page: number, x: number, y: number, existingFields?: FormField[]): FormField;
+
+type TransformFn = (value: string) => string;
+type TransformMap = Record<string, TransformFn>;
+/**
+ * Parse a date string robustly into a local Date (midnight, local TZ) so that
+ * getMonth/getDate/getFullYear are calendar-correct. Handles:
+ *  - ISO date-only "YYYY-MM-DD" → parsed as LOCAL (avoids the classic UTC
+ *    off-by-one where "2024-03-15" becomes the 14th in western timezones).
+ *  - Excel serial numbers (a bare integer, e.g. "45000") → converted.
+ *  - Anything else → native `new Date` (handles "M/D/YYYY", ISO datetimes, …).
+ * Returns null when unparseable.
+ */
+declare function parseDate(value: string): Date | null;
+/** Built-in transforms that ship with exeq. */
+declare const BUILTIN_TRANSFORMS: TransformMap;
+/**
+ * Resolve a single formula string against a set of fields and transforms.
+ * Formula format: "{{Source Field Label | transform}}" or "{{Source Field Label}}" (no transform = raw value).
+ * Multiple expressions can appear in one formula: "{{First}} {{Last}}" → "Jane Smith"
+ *
+ * Source resolution order for "{{Name}}":
+ *   1. a placed field whose label (case-insensitive) or id matches Name
+ *   2. `values[Name]` — imported/contextual data not tied to a placed field
+ *   3. the built-in `today` / `now` source (current date)
+ *
+ * @param values Extra named values (e.g. imported CSV/form data) made available
+ *   to formula sources even when there is no placed field for them.
+ */
+declare function resolveFormula(formula: string, fields: FormField[], customTransforms?: TransformMap, values?: Record<string, string>): string;
+/**
+ * Resolve all formula fields in a fields array.
+ * Returns a new array with computed values filled in.
+ *
+ * @param values Extra named values available to formula sources (see resolveFormula).
+ */
+declare function resolveAllFormulas(fields: FormField[], customTransforms?: TransformMap, values?: Record<string, string>): FormField[];
+
+/** 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;
+    /** Extra named values made available to formula sources (e.g. imported CSV/
+     * form data) even when there is no placed field for them. Only meaningful
+     * when `resolveFormulas` is true. */
+    formulaValues?: Record<string, string>;
+    /** 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, builderOptions?: Omit<CreatePdfBuilderOptions, 'pageSize'>): 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>;
+}
+/** Document-level metadata applied at `save()` time. */
+interface PdfMetadata {
+    title?: string;
+    author?: string;
+    subject?: string;
+    creator?: string;
+    producer?: string;
+    /** Document creation date. Pin to a fixed `Date` for reproducible output. */
+    creationDate?: Date;
+    /** Document modification date. Pin to a fixed `Date` for reproducible output. */
+    modificationDate?: Date;
+}
+interface CreatePdfBuilderOptions {
+    /** Default `pageSize` for any `addRecord` call that doesn't set its own. */
+    pageSize?: [number, number];
+    /** Document metadata applied at `save()` time. Pin `creationDate` and
+     *  `modificationDate` to fixed `Date`s for byte-identical output across runs
+     *  — pdf-lib otherwise stamps the current time, so two runs of identical
+     *  input would differ. Useful for server-side generation and caching. */
+    metadata?: PdfMetadata;
+}
+/**
+ * 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 { A4 as A, BUILTIN_TRANSFORMS as B, type Calibration as C, DEFAULT_CALIBRATION as D, preserveFieldValues as E, type FormField as F, resolveAllFormulas as G, resolveFormula as H, sortFieldsByPosition as I, uniqueLabel as J, type PdfBuilder as P, SIGNER_ROLE_COLORS as S, type Template as T, US_LEGAL as U, type TransformMap as a, type FieldType as b, type CreatePdfBuilderOptions as c, DEFAULT_SIGNER_ROLES as d, FIELD_DEFAULTS as e, FONT_FAMILIES as f, type FillPdfOptions as g, type PdfMetadata as h, type TextSubtype as i, type TransformFn as j, US_LETTER as k, applyCalibration as l, createField as m, createPdfBuilder as n, downloadPdf as o, generateFilledPdf as p, generateId as q, getCssFontFamily as r, getFieldValues as s, getInputType as t, getSignerColor as u, isRedactField as v, isSignatureField as w, isTextLikeField as x, parseDate as y, postPdfToCallback as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unlev/exeq",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Embeddable PDF form builder and document signing — client-side, no backend required",
   "license": "MIT",
   "main": "dist/index.js",
@@ -20,20 +20,7 @@
     "./styles": "./dist/index.css"
   },
   "files": [
-    "dist/index.js",
-    "dist/index.mjs",
-    "dist/index.d.ts",
-    "dist/index.d.mts",
-    "dist/index.css",
-    "dist/index.css.map",
-    "dist/index.js.map",
-    "dist/index.mjs.map",
-    "dist/server.js",
-    "dist/server.mjs",
-    "dist/server.d.ts",
-    "dist/server.d.mts",
-    "dist/server.js.map",
-    "dist/server.mjs.map"
+    "dist"
   ],
   "sideEffects": [
     "*.css"