pdf-lite 1.6.2 → 1.6.3

package/EXAMPLES.md

@@ -1989,3 +1989,292 @@ async function main() {
 
 main().catch(console.error)
 ```
+
+## JavaScript Actions example - Executing JS actions in PDF form fields
+
+```typescript
+//
+// PDF forms generated by Adobe Acrobat and LiveCycle often include JavaScript
+// actions for formatting, validation, and field calculations. The
+// PdfJavaScriptEngine executes these automatically when setting field values,
+// with built-in support for common Acrobat JS functions.
+
+import { PdfArray } from 'pdf-lite/core/objects/pdf-array'
+import { PdfBoolean } from 'pdf-lite/core/objects/pdf-boolean'
+import { PdfDictionary } from 'pdf-lite/core/objects/pdf-dictionary'
+import { PdfIndirectObject } from 'pdf-lite/core/objects/pdf-indirect-object'
+import { PdfName } from 'pdf-lite/core/objects/pdf-name'
+import { PdfNumber } from 'pdf-lite/core/objects/pdf-number'
+import { PdfObjectReference } from 'pdf-lite/core/objects/pdf-object-reference'
+import { PdfStream } from 'pdf-lite/core/objects/pdf-stream'
+import { PdfString } from 'pdf-lite/core/objects/pdf-string'
+import { PdfDocument } from 'pdf-lite/pdf/pdf-document'
+import { PdfJavaScriptEngine } from 'pdf-lite/acroform/js/pdf-js-engine-impl'
+import fs from 'fs/promises'
+
+const tmpFolder = `${import.meta.dirname}/tmp`
+await fs.mkdir(tmpFolder, { recursive: true })
+
+// ============================================
+// Helpers
+// ============================================
+
+function createPage(
+    contentStreamRef: PdfObjectReference,
+): PdfIndirectObject<PdfDictionary> {
+    const d = new PdfDictionary()
+    d.set('Type', new PdfName('Page'))
+    d.set(
+        'MediaBox',
+        new PdfArray([
+            new PdfNumber(0),
+            new PdfNumber(0),
+            new PdfNumber(612),
+            new PdfNumber(792),
+        ]),
+    )
+    d.set('Contents', contentStreamRef)
+    return new PdfIndirectObject({ content: d })
+}
+
+function createPages(
+    pages: PdfIndirectObject<PdfDictionary>[],
+): PdfIndirectObject<PdfDictionary> {
+    const d = new PdfDictionary()
+    d.set('Type', new PdfName('Pages'))
+    d.set('Kids', new PdfArray(pages.map((x) => x.reference)))
+    d.set('Count', new PdfNumber(pages.length))
+    return new PdfIndirectObject({ content: d })
+}
+
+function createCatalog(
+    pagesRef: PdfObjectReference,
+): PdfIndirectObject<PdfDictionary> {
+    const d = new PdfDictionary()
+    d.set('Type', new PdfName('Catalog'))
+    d.set('Pages', pagesRef)
+    return new PdfIndirectObject({ content: d })
+}
+
+/** Create a text field with an optional JavaScript format action. */
+function createTextField(
+    fieldName: string,
+    pageRef: PdfObjectReference,
+    rect: [number, number, number, number],
+    jsFormatCode?: string,
+    jsCalcCode?: string,
+): PdfIndirectObject<PdfDictionary> {
+    const d = new PdfDictionary()
+    d.set('Type', new PdfName('Annot'))
+    d.set('Subtype', new PdfName('Widget'))
+    d.set('FT', new PdfName('Tx'))
+    d.set('T', new PdfString(fieldName))
+    d.set(
+        'Rect',
+        new PdfArray([
+            new PdfNumber(rect[0]),
+            new PdfNumber(rect[1]),
+            new PdfNumber(rect[2]),
+            new PdfNumber(rect[3]),
+        ]),
+    )
+    d.set('F', new PdfNumber(4))
+    d.set('P', pageRef)
+    d.set('DA', new PdfString('/Helv 12 Tf 0 g'))
+
+    // Add /AA (additional actions) dictionary with JS format/calculate actions
+    if (jsFormatCode || jsCalcCode) {
+        const aa = new PdfDictionary()
+        if (jsFormatCode) {
+            const fmtAction = new PdfDictionary()
+            fmtAction.set('S', new PdfName('JavaScript'))
+            fmtAction.set('JS', new PdfString(jsFormatCode))
+            aa.set('F', fmtAction)
+        }
+        if (jsCalcCode) {
+            const calcAction = new PdfDictionary()
+            calcAction.set('S', new PdfName('JavaScript'))
+            calcAction.set('JS', new PdfString(jsCalcCode))
+            aa.set('C', calcAction)
+        }
+        d.set('AA', aa)
+    }
+
+    return new PdfIndirectObject({ content: d })
+}
+
+// ============================================
+// Build a PDF with JS-powered form fields
+// ============================================
+
+const document = new PdfDocument()
+
+// Font
+const font = new PdfDictionary()
+font.set('Type', new PdfName('Font'))
+font.set('Subtype', new PdfName('Type1'))
+font.set('BaseFont', new PdfName('Helvetica'))
+const fontObj = new PdfIndirectObject({ content: font })
+document.add(fontObj)
+
+// Resources
+const resources = new PdfDictionary()
+const fontDict = new PdfDictionary()
+fontDict.set('F1', fontObj.reference)
+resources.set('Font', fontDict)
+const resourcesObj = new PdfIndirectObject({ content: resources })
+document.add(resourcesObj)
+
+// Content stream with labels
+const contentStream = new PdfIndirectObject({
+    content: new PdfStream({
+        header: new PdfDictionary(),
+        original: `BT
+/F1 18 Tf 72 720 Td (Invoice - JS Actions Demo) Tj
+/F1 12 Tf 0 -50 Td (Price:) Tj
+0 -30 Td (Quantity:) Tj
+0 -30 Td (Total:) Tj
+0 -40 Td (Phone:) Tj
+ET `,
+    }),
+})
+document.add(contentStream)
+
+// Page
+const page = createPage(contentStream.reference)
+page.content.set('Resources', resourcesObj.reference)
+document.add(page)
+
+// Form fields with JavaScript actions:
+
+// Price field — formats as currency via AFNumber_Format
+const priceField = createTextField(
+    'Price',
+    page.reference,
+    [150, 655, 350, 675],
+    'AFNumber_Format(2, 0, 0, 0, "$", true)',
+)
+document.add(priceField)
+
+// Quantity field — plain number format
+const qtyField = createTextField(
+    'Quantity',
+    page.reference,
+    [150, 625, 350, 645],
+    'AFNumber_Format(0, 0, 0, 0, "", false)',
+)
+document.add(qtyField)
+
+// Total field — calculated as Price * Quantity via AFSimple_Calculate
+const totalField = createTextField(
+    'Total',
+    page.reference,
+    [150, 595, 350, 615],
+    'AFNumber_Format(2, 0, 0, 0, "$", true)',
+    'AFSimple_Calculate("PRD", ["Price", "Quantity"])',
+)
+document.add(totalField)
+
+// Phone field — formatted via AFSpecial_Format (phone)
+const phoneField = createTextField(
+    'Phone',
+    page.reference,
+    [150, 555, 350, 575],
+    'AFSpecial_Format(2)',
+)
+document.add(phoneField)
+
+// Annotations on page
+page.content.set(
+    'Annots',
+    new PdfArray([
+        priceField.reference,
+        qtyField.reference,
+        totalField.reference,
+        phoneField.reference,
+    ]),
+)
+
+// Pages / catalog
+const pages = createPages([page])
+page.content.set('Parent', pages.reference)
+document.add(pages)
+
+const catalog = createCatalog(pages.reference)
+
+// AcroForm with fields and calculation order
+const acroForm = new PdfDictionary()
+acroForm.set(
+    'Fields',
+    new PdfArray([
+        priceField.reference,
+        qtyField.reference,
+        totalField.reference,
+        phoneField.reference,
+    ]),
+)
+// Calculation order — Total depends on Price and Quantity
+acroForm.set('CO', new PdfArray([totalField.reference]))
+acroForm.set('NeedAppearances', new PdfBoolean(true))
+
+// Form default resources
+const formResources = new PdfDictionary()
+const formFontDict = new PdfDictionary()
+const helvetica = new PdfDictionary()
+helvetica.set('Type', new PdfName('Font'))
+helvetica.set('Subtype', new PdfName('Type1'))
+helvetica.set('BaseFont', new PdfName('Helvetica'))
+const helveticaObj = new PdfIndirectObject({ content: helvetica })
+document.add(helveticaObj)
+formFontDict.set('Helv', helveticaObj.reference)
+formResources.set('Font', formFontDict)
+acroForm.set('DR', formResources)
+acroForm.set('DA', new PdfString('/Helv 12 Tf 0 g'))
+
+const acroFormObj = new PdfIndirectObject({ content: acroForm })
+document.add(acroFormObj)
+catalog.content.set('AcroForm', acroFormObj.reference)
+document.add(catalog)
+document.trailerDict.set('Root', catalog.reference)
+
+await document.finalize()
+await fs.writeFile(`${tmpFolder}/js-actions-form.pdf`, document.toBytes())
+console.log('Created js-actions-form.pdf with JavaScript action fields')
+
+// ============================================
+// Fill the form with the JS engine enabled
+// ============================================
+
+const formBytes = await fs.readFile(`${tmpFolder}/js-actions-form.pdf`)
+const filledDoc = await PdfDocument.fromBytes([formBytes])
+const form = filledDoc.acroform!
+
+// Attach the JS engine with a field value resolver for AFSimple_Calculate
+form.jsEngine = new PdfJavaScriptEngine({
+    getFieldValue: (name) => {
+        const field = form.fields.find((f) => f.name === name)
+        return field?.value ?? ''
+    },
+})
+
+// Set values — JS format actions fire automatically
+form.setValues({
+    Price: '49.99',
+    Quantity: '3',
+    Phone: '5551234567',
+})
+
+// Print resulting values (after JS actions have run)
+console.log('\nField values after JS actions:')
+for (const field of form.fields) {
+    console.log(`  ${field.name}: "${field.value}"`)
+}
+// Expected output:
+//   Price: "$49.99"
+//   Quantity: "3"
+//   Total: "$149.97"  (calculated via AFSimple_Calculate PRD)
+//   Phone: "(555) 123-4567"  (formatted via AFSpecial_Format)
+
+await fs.writeFile(`${tmpFolder}/js-actions-filled.pdf`, filledDoc.toBytes())
+console.log('\nCreated js-actions-filled.pdf with JS-formatted values')
+```

package/README.md

@@ -52,7 +52,7 @@ import { PdfArray } from 'pdf-lite/core/objects/pdf-array'
 import { PdfNumber } from 'pdf-lite/core/objects/pdf-number'
 
 // Create the document
-const document = new PdfDocument()
+const doc = new PdfDocument()
 
 // Create content stream
 const contentStream = new PdfIndirectObject({
@@ -62,12 +62,12 @@ const contentStream = new PdfIndirectObject({
     }),
 })
 
-// Create and commit objects
-document.commit(contentStream)
+// Create and add objects
+doc.add(contentStream)
 // ... create pages, catalog, etc.
 
 // Output the PDF
-console.log(document.toString())
+console.log(doc.toString())
 ```
 
 ### Working with Encryption
@@ -113,7 +113,7 @@ form.setValues({
 
 // Or work with individual fields
 const field = form.fields.find((f) => f.name === 'name')
-field.value = 'Jane Doe'
+if (field) field.value = 'Jane Doe'
 
 // Export all current values
 const values = form.exportData()
@@ -127,6 +127,14 @@ await writeFile('filled.pdf', doc.toBytes())
 Appearance streams control how form fields render visually. The library can automatically generate them when field values are set, or you can generate them manually.
 
 ```typescript
+import { PdfButtonFormField } from 'pdf-lite/acroform/fields/pdf-button-form-field'
+import { PdfChoiceFormField } from 'pdf-lite/acroform/fields/pdf-choice-form-field'
+import { PdfAcroForm } from 'pdf-lite/acroform/pdf-acro-form'
+import { PdfTextFormField } from 'pdf-lite/acroform/fields/pdf-text-form-field'
+
+declare const form: PdfAcroForm
+declare const field: PdfTextFormField
+
 // Auto-generate appearances when setting values (default behavior)
 field.value = 'Hello' // appearance is generated automatically
 
@@ -138,12 +146,16 @@ field.fontSize = 14
 field.fontName = 'Helv'
 
 // For checkbox fields
-const checkbox = form.fields.find((f) => f.name === 'agree')
+const checkbox = form.fields.find(
+    (f) => f.name === 'agree',
+) as PdfButtonFormField
 checkbox.checked = true
 checkbox.generateAppearance()
 
 // For choice fields (dropdowns/listboxes)
-const dropdown = form.fields.find((f) => f.name === 'country')
+const dropdown = form.fields.find(
+    (f) => f.name === 'country',
+) as PdfChoiceFormField
 dropdown.value = 'US'
 dropdown.generateAppearance()
 ```
@@ -152,6 +164,8 @@ dropdown.generateAppearance()
 
 ```typescript
 import { PdfFont } from 'pdf-lite'
+import { PdfDocument } from 'pdf-lite/pdf/pdf-document'
+import { readFileSync } from 'fs'
 
 // Standard PDF fonts (built into all PDF readers)
 const helvetica = PdfFont.fromStandardFont('Helvetica')
@@ -159,7 +173,6 @@ const timesBold = PdfFont.fromStandardFont('Times-Bold')
 const courier = PdfFont.fromStandardFont('Courier')
 
 // Embed custom fonts from file bytes (auto-detects TTF, OTF, WOFF)
-import { readFileSync } from 'fs'
 const fontData = readFileSync('MyFont.ttf')
 const customFont = PdfFont.fromBytes(fontData)
 
@@ -170,7 +183,8 @@ const font = PdfFont.HELVETICA_BOLD
 customFont.resourceName = 'F1'
 
 // Add to document
-document.add(customFont)
+const doc = new PdfDocument()
+doc.add(customFont)
 ```
 
 **Standard font names:** Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique, Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic, Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique, Symbol, ZapfDingbats
@@ -289,6 +303,16 @@ Supports reading, filling, and creating AcroForm fields within PDF documents.
 - [x] Read individual field properties (name, value, type, flags)
 - [x] Hierarchical field support (parent/child/sibling fields)
 
+**JavaScript actions:**
+
+- [x] JavaScript action execution via `PdfJavaScriptEngine`
+- [x] Validate, keystroke, calculate, and format action triggers
+- [x] Built-in Acrobat JS functions: `util.printd`, `util.scand`, `util.printf`
+- [x] `AFNumber_Format` / `AFNumber_Keystroke` — number formatting and validation
+- [x] `AFDate_FormatEx` / `AFDate_KeystrokeEx` — date formatting and validation
+- [x] `AFSimple_Calculate` — SUM, AVG, PRD, MIN, MAX across fields
+- [x] `AFSpecial_Format` / `AFSpecial_Keystroke` — zip, SSN, phone formatting
+
 ### Appearance Streams
 
 Automatic generation of visual appearance streams for form fields, so filled forms render correctly in all PDF viewers without relying on `NeedAppearances`.

package/dist/acroform/fields/pdf-form-field.d.ts

@@ -10,6 +10,8 @@ import type { PdfFieldType } from './types.js';
 import { PdfFormFieldFlags } from './pdf-form-field-flags.js';
 import { PdfDefaultResourcesDictionary } from '../../annotations/pdf-default-resources.js';
 import type { PdfAcroForm } from '../pdf-acro-form.js';
+import { PdfFieldActions } from '../js/pdf-field-actions.js';
+import { PdfJavaScriptAction } from '../js/pdf-javascript-action.js';
 /**
  * Abstract base form field class. Extends PdfWidgetAnnotation with form-specific properties:
  * FT, V, DA, Ff, T (name), field hierarchy (parent/children/siblings).
@@ -100,6 +102,9 @@ export declare abstract class PdfFormField extends PdfWidgetAnnotation {
     set maxLen(maxLen: number | null);
     get kids(): PdfArray<PdfObjectReference> | undefined;
     set kids(kids: PdfObjectReference[]);
+    private _resolveActionDict;
+    get actions(): PdfFieldActions | null;
+    get activateAction(): PdfJavaScriptAction | null;
     abstract generateAppearance(options?: {
         makeReadOnly?: boolean;
         textYOffset?: number;

package/dist/acroform/fields/pdf-form-field.js

@@ -12,6 +12,8 @@ import { PdfWidgetAnnotation } from '../../annotations/pdf-widget-annotation.js'
 import { PdfDefaultAppearance } from './pdf-default-appearance.js';
 import { PdfFieldType as PdfFieldTypeConst } from './types.js';
 import { PdfFormFieldFlags } from './pdf-form-field-flags.js';
+import { PdfFieldActions } from '../js/pdf-field-actions.js';
+import { PdfJavaScriptAction } from '../js/pdf-javascript-action.js';
 /**
  * Abstract base form field class. Extends PdfWidgetAnnotation with form-specific properties:
  * FT, V, DA, Ff, T (name), field hierarchy (parent/children/siblings).
@@ -467,6 +469,36 @@ export class PdfFormField extends PdfWidgetAnnotation {
         const kidsArray = new PdfArray(kids);
         this.content.set('Kids', kidsArray);
     }
+    _resolveActionDict(key) {
+        const entry = this.content.get(key);
+        if (entry instanceof PdfObjectReference) {
+            const resolved = entry.resolve();
+            if (resolved?.content instanceof PdfDictionary) {
+                return resolved.content;
+            }
+        }
+        else if (entry instanceof PdfDictionary) {
+            return entry;
+        }
+        return undefined;
+    }
+    get actions() {
+        const aaDict = this._resolveActionDict('AA');
+        if (!aaDict)
+            return null;
+        return aaDict.becomes(PdfFieldActions, {
+            activateDict: this._resolveActionDict('A'),
+            engine: this._form?.jsEngine,
+        });
+    }
+    get activateAction() {
+        const aDict = this._resolveActionDict('A');
+        if (!aDict)
+            return null;
+        return aDict.becomes(PdfJavaScriptAction, {
+            engine: this._form?.jsEngine,
+        });
+    }
     setAppearanceStream(stream) {
         this.appearanceStreamDict ||= new PdfDictionary();
         if (stream instanceof PdfIndirectObject) {

package/dist/acroform/index.d.ts

@@ -2,3 +2,4 @@ export * from './pdf-acro-form.js';
 export * from './fields/index.js';
 export * from './appearance/index.js';
 export * from './xfa/index.js';
+export * from './js/index.js';

package/dist/acroform/index.js

@@ -2,3 +2,4 @@ export * from './pdf-acro-form.js';
 export * from './fields/index.js';
 export * from './appearance/index.js';
 export * from './xfa/index.js';
+export * from './js/index.js';

package/dist/acroform/js/index.d.ts

@@ -0,0 +1,5 @@
+export * from './pdf-js-engine.js';
+export * from './pdf-js-engine-impl.js';
+export * from './pdf-js-builtins.js';
+export * from './pdf-javascript-action.js';
+export * from './pdf-field-actions.js';

package/dist/acroform/js/index.js

@@ -0,0 +1,5 @@
+export * from './pdf-js-engine.js';
+export * from './pdf-js-engine-impl.js';
+export * from './pdf-js-builtins.js';
+export * from './pdf-javascript-action.js';
+export * from './pdf-field-actions.js';

package/dist/acroform/js/pdf-field-actions.d.ts

@@ -0,0 +1,17 @@
+import { PdfDictionary } from '../../core/objects/pdf-dictionary.js';
+import { PdfJavaScriptAction } from './pdf-javascript-action.js';
+import type { PdfJsEngine } from './pdf-js-engine.js';
+export declare class PdfFieldActions extends PdfDictionary {
+    private readonly activateDict?;
+    readonly engine?: PdfJsEngine;
+    constructor(dict: PdfDictionary, options?: {
+        activateDict?: PdfDictionary;
+        engine?: PdfJsEngine;
+    });
+    private _resolve;
+    get keystroke(): PdfJavaScriptAction | null;
+    get validate(): PdfJavaScriptAction | null;
+    get calculate(): PdfJavaScriptAction | null;
+    get format(): PdfJavaScriptAction | null;
+    get activate(): PdfJavaScriptAction | null;
+}

package/dist/acroform/js/pdf-field-actions.js

@@ -0,0 +1,52 @@
+import { PdfDictionary } from '../../core/objects/pdf-dictionary.js';
+import { PdfObjectReference } from '../../core/objects/pdf-object-reference.js';
+import { PdfJavaScriptAction } from './pdf-javascript-action.js';
+export class PdfFieldActions extends PdfDictionary {
+    activateDict;
+    engine;
+    constructor(dict, options) {
+        super();
+        this.copyFrom(dict);
+        this.activateDict = options?.activateDict;
+        this.engine = options?.engine;
+    }
+    _resolve(key) {
+        const entry = this.get(key);
+        if (!entry)
+            return null;
+        let actionDict;
+        if (entry instanceof PdfObjectReference) {
+            const resolved = entry.resolve();
+            if (resolved?.content instanceof PdfDictionary) {
+                actionDict = resolved.content;
+            }
+        }
+        else if (entry instanceof PdfDictionary) {
+            actionDict = entry;
+        }
+        if (!actionDict)
+            return null;
+        return actionDict.becomes(PdfJavaScriptAction, {
+            engine: this.engine,
+        });
+    }
+    get keystroke() {
+        return this._resolve('K');
+    }
+    get validate() {
+        return this._resolve('V');
+    }
+    get calculate() {
+        return this._resolve('C');
+    }
+    get format() {
+        return this._resolve('F');
+    }
+    get activate() {
+        if (!this.activateDict)
+            return null;
+        return this.activateDict.becomes(PdfJavaScriptAction, {
+            engine: this.engine,
+        });
+    }
+}

package/dist/acroform/js/pdf-javascript-action.d.ts

@@ -0,0 +1,17 @@
+import { PdfDictionary } from '../../core/objects/pdf-dictionary.js';
+import { PdfString } from '../../core/objects/pdf-string.js';
+import { PdfStream } from '../../core/objects/pdf-stream.js';
+import { PdfObjectReference } from '../../core/objects/pdf-object-reference.js';
+import { PdfName } from '../../core/objects/pdf-name.js';
+import type { PdfJsEngine, PdfJsEvent } from './pdf-js-engine.js';
+export declare class PdfJavaScriptAction extends PdfDictionary<{
+    S?: PdfName;
+    JS?: PdfString | PdfStream | PdfObjectReference;
+}> {
+    engine?: PdfJsEngine;
+    constructor(dict: PdfDictionary, options?: {
+        engine?: PdfJsEngine;
+    });
+    get code(): string | null;
+    execute(event: PdfJsEvent): void;
+}

package/dist/acroform/js/pdf-javascript-action.js

@@ -0,0 +1,38 @@
+import { PdfDictionary } from '../../core/objects/pdf-dictionary.js';
+import { PdfString } from '../../core/objects/pdf-string.js';
+import { PdfStream } from '../../core/objects/pdf-stream.js';
+import { PdfObjectReference } from '../../core/objects/pdf-object-reference.js';
+import { bytesToString } from '../../utils/bytesToString.js';
+export class PdfJavaScriptAction extends PdfDictionary {
+    engine;
+    constructor(dict, options) {
+        super();
+        this.copyFrom(dict);
+        this.engine = options?.engine;
+    }
+    get code() {
+        const js = this.get('JS');
+        if (js instanceof PdfString) {
+            return js.value;
+        }
+        if (js instanceof PdfObjectReference) {
+            const resolved = js.resolve();
+            if (resolved?.content instanceof PdfStream) {
+                return bytesToString(resolved.content.data);
+            }
+            if (resolved?.content instanceof PdfString) {
+                return resolved.content.value;
+            }
+        }
+        if (js instanceof PdfStream) {
+            return bytesToString(js.data);
+        }
+        return null;
+    }
+    execute(event) {
+        const code = this.code;
+        if (code && this.engine) {
+            this.engine.execute(code, event);
+        }
+    }
+}

package/dist/acroform/js/pdf-js-builtins.d.ts

@@ -0,0 +1,12 @@
+import type { PdfJsEvent } from './pdf-js-engine.js';
+export declare function printd(fmt: string, date: Date): string;
+export declare function scand(fmt: string, str: string): Date | null;
+export declare function printf(fmt: string, ...args: unknown[]): string;
+export declare const util: {
+    printd: typeof printd;
+    scand: typeof scand;
+    printf: typeof printf;
+};
+type GetFieldValue = (name: string) => string;
+export declare function createBuiltins(event: PdfJsEvent, getFieldValue?: GetFieldValue): Record<string, unknown>;
+export {};

package/dist/acroform/js/pdf-js-builtins.js

@@ -0,0 +1,454 @@
+// ---------------------------------------------------------------------------
+// util.printd — format a Date as a string using Acrobat date tokens
+// ---------------------------------------------------------------------------
+const MONTH_NAMES = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+];
+const MONTH_ABBR = [
+    'Jan',
+    'Feb',
+    'Mar',
+    'Apr',
+    'May',
+    'Jun',
+    'Jul',
+    'Aug',
+    'Sep',
+    'Oct',
+    'Nov',
+    'Dec',
+];
+const DAY_NAMES = [
+    'Sunday',
+    'Monday',
+    'Tuesday',
+    'Wednesday',
+    'Thursday',
+    'Friday',
+    'Saturday',
+];
+const DAY_ABBR = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+function pad(n, len) {
+    return String(n).padStart(len, '0');
+}
+export function printd(fmt, date) {
+    const y = date.getFullYear();
+    const M = date.getMonth(); // 0-based
+    const d = date.getDate();
+    const dow = date.getDay();
+    const H = date.getHours();
+    const m = date.getMinutes();
+    const s = date.getSeconds();
+    const h12 = H % 12 || 12;
+    // Replace tokens longest-first to avoid partial matches
+    return fmt
+        .replace(/yyyy/g, String(y))
+        .replace(/yy/g, pad(y % 100, 2))
+        .replace(/mmmm/g, MONTH_NAMES[M])
+        .replace(/mmm/g, MONTH_ABBR[M])
+        .replace(/mm/g, pad(M + 1, 2))
+        .replace(/(?<![\w])m(?![\w])/g, String(M + 1))
+        .replace(/dddd/g, DAY_NAMES[dow])
+        .replace(/ddd/g, DAY_ABBR[dow])
+        .replace(/dd/g, pad(d, 2))
+        .replace(/(?<![\w])d(?![\w])/g, String(d))
+        .replace(/HH/g, pad(H, 2))
+        .replace(/hh/g, pad(h12, 2))
+        .replace(/(?<![\w])h(?![\w])/g, String(h12))
+        .replace(/MM/g, pad(m, 2))
+        .replace(/ss/g, pad(s, 2))
+        .replace(/tt/g, H < 12 ? 'AM' : 'PM')
+        .replace(/(?<![\w])t(?![\w])/g, H < 12 ? 'am' : 'pm');
+}
+// ---------------------------------------------------------------------------
+// util.scand — parse a date string using an Acrobat format
+// ---------------------------------------------------------------------------
+export function scand(fmt, str) {
+    // Build a regex from the format, capturing groups for each token
+    const tokens = [];
+    let pattern = '';
+    let i = 0;
+    while (i < fmt.length) {
+        let matched = false;
+        for (const tok of [
+            'yyyy',
+            'yy',
+            'mmmm',
+            'mmm',
+            'mm',
+            'm',
+            'dddd',
+            'ddd',
+            'dd',
+            'd',
+            'HH',
+            'hh',
+            'h',
+            'MM',
+            'ss',
+        ]) {
+            if (fmt.substring(i, i + tok.length) === tok) {
+                tokens.push({ token: tok, index: tokens.length });
+                switch (tok) {
+                    case 'yyyy':
+                        pattern += '(\\d{4})';
+                        break;
+                    case 'yy':
+                        pattern += '(\\d{2})';
+                        break;
+                    case 'mmmm':
+                        pattern += '([A-Za-z]+)';
+                        break;
+                    case 'mmm':
+                        pattern += '([A-Za-z]{3})';
+                        break;
+                    case 'mm':
+                        pattern += '(\\d{2})';
+                        break;
+                    case 'm':
+                        pattern += '(\\d{1,2})';
+                        break;
+                    case 'dddd':
+                        pattern += '([A-Za-z]+)';
+                        break;
+                    case 'ddd':
+                        pattern += '([A-Za-z]{3})';
+                        break;
+                    case 'dd':
+                        pattern += '(\\d{2})';
+                        break;
+                    case 'd':
+                        pattern += '(\\d{1,2})';
+                        break;
+                    case 'HH':
+                    case 'hh':
+                        pattern += '(\\d{2})';
+                        break;
+                    case 'h':
+                        pattern += '(\\d{1,2})';
+                        break;
+                    case 'MM':
+                        pattern += '(\\d{2})';
+                        break;
+                    case 'ss':
+                        pattern += '(\\d{2})';
+                        break;
+                }
+                i += tok.length;
+                matched = true;
+                break;
+            }
+        }
+        if (!matched) {
+            pattern += fmt[i].replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            i++;
+        }
+    }
+    const re = new RegExp('^' + pattern + '$');
+    const match = str.match(re);
+    if (!match)
+        return null;
+    let year = 0, month = 0, day = 1, hours = 0, minutes = 0, seconds = 0;
+    for (const { token, index } of tokens) {
+        const val = match[index + 1];
+        switch (token) {
+            case 'yyyy':
+                year = parseInt(val, 10);
+                break;
+            case 'yy': {
+                const n = parseInt(val, 10);
+                year = n < 50 ? 2000 + n : 1900 + n;
+                break;
+            }
+            case 'mmmm': {
+                const idx = MONTH_NAMES.findIndex((m) => m.toLowerCase() === val.toLowerCase());
+                if (idx >= 0)
+                    month = idx;
+                break;
+            }
+            case 'mmm': {
+                const idx = MONTH_ABBR.findIndex((m) => m.toLowerCase() === val.toLowerCase());
+                if (idx >= 0)
+                    month = idx;
+                break;
+            }
+            case 'mm':
+            case 'm':
+                month = parseInt(val, 10) - 1;
+                break;
+            case 'dd':
+            case 'd':
+                day = parseInt(val, 10);
+                break;
+            case 'HH':
+            case 'hh':
+            case 'h':
+                hours = parseInt(val, 10);
+                break;
+            case 'MM':
+                minutes = parseInt(val, 10);
+                break;
+            case 'ss':
+                seconds = parseInt(val, 10);
+                break;
+            // dddd/ddd are day-of-week names — informational only, ignored
+        }
+    }
+    return new Date(year, month, day, hours, minutes, seconds);
+}
+// ---------------------------------------------------------------------------
+// util.printf — sprintf subset: %d, %f, %s with width/precision/flags
+// ---------------------------------------------------------------------------
+export function printf(fmt, ...args) {
+    let argIdx = 0;
+    return fmt.replace(/%([0 #+-]*)(\d+)?(?:\.(\d+))?([dfsxXo%])/g, (_match, flags, widthStr, precStr, type) => {
+        if (type === '%')
+            return '%';
+        const val = args[argIdx++];
+        const width = widthStr ? parseInt(widthStr, 10) : 0;
+        const prec = precStr !== undefined ? parseInt(precStr, 10) : undefined;
+        const leftAlign = flags.includes('-');
+        const zeroPad = flags.includes('0') && !leftAlign;
+        const plusSign = flags.includes('+');
+        const spaceSign = flags.includes(' ');
+        let result;
+        switch (type) {
+            case 'd': {
+                const n = Math.trunc(Number(val));
+                const sign = n < 0 ? '-' : plusSign ? '+' : spaceSign ? ' ' : '';
+                const digits = String(Math.abs(n));
+                result =
+                    sign +
+                        (zeroPad
+                            ? digits.padStart(Math.max(0, width - sign.length), '0')
+                            : digits);
+                break;
+            }
+            case 'f': {
+                const n = Number(val);
+                const p = prec !== undefined ? prec : 6;
+                const sign = n < 0 ? '-' : plusSign ? '+' : spaceSign ? ' ' : '';
+                const formatted = Math.abs(n).toFixed(p);
+                result =
+                    sign +
+                        (zeroPad
+                            ? formatted.padStart(Math.max(0, width - sign.length), '0')
+                            : formatted);
+                break;
+            }
+            case 'x':
+                result = (Math.trunc(Number(val)) >>> 0).toString(16);
+                break;
+            case 'X':
+                result = (Math.trunc(Number(val)) >>> 0)
+                    .toString(16)
+                    .toUpperCase();
+                break;
+            case 'o':
+                result = (Math.trunc(Number(val)) >>> 0).toString(8);
+                break;
+            case 's':
+            default:
+                result = String(val);
+                if (prec !== undefined)
+                    result = result.slice(0, prec);
+                break;
+        }
+        if (result.length < width) {
+            result = leftAlign
+                ? result.padEnd(width)
+                : result.padStart(width, zeroPad ? '0' : ' ');
+        }
+        return result;
+    });
+}
+// ---------------------------------------------------------------------------
+// util object
+// ---------------------------------------------------------------------------
+export const util = { printd, scand, printf };
+function parseNumericValue(str) {
+    // Strip currency symbols, spaces, commas
+    const cleaned = str.replace(/[^0-9.\-eE]/g, '');
+    const n = parseFloat(cleaned);
+    return isNaN(n) ? 0 : n;
+}
+function formatNumber(value, nDec, sepStyle, negStyle, _currStyle, strCurrency, bCurrencyPrepend) {
+    const absVal = Math.abs(value);
+    const fixed = absVal.toFixed(nDec);
+    // sepStyle: 0 = 1,234.56  1 = 1234.56  2 = 1.234,56  3 = 1234,56
+    let [intPart, decPart] = fixed.split('.');
+    const decSep = sepStyle >= 2 ? ',' : '.';
+    const thousandSep = sepStyle === 0 ? ',' : sepStyle === 2 ? '.' : '';
+    if (thousandSep) {
+        intPart = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, thousandSep);
+    }
+    let formatted = decPart !== undefined ? intPart + decSep + decPart : intPart;
+    // Currency
+    if (strCurrency) {
+        if (bCurrencyPrepend) {
+            formatted = strCurrency + formatted;
+        }
+        else {
+            formatted = formatted + strCurrency;
+        }
+    }
+    // Negative style: 0 = -val  1 = red text (we just use -)  2 = (val)  3 = (val) red
+    if (value < 0) {
+        if (negStyle === 0 || negStyle === 1) {
+            formatted = '-' + formatted;
+        }
+        else {
+            formatted = '(' + formatted + ')';
+        }
+    }
+    return formatted;
+}
+export function createBuiltins(event, getFieldValue) {
+    // --- AF functions that close over event ---
+    function AFDate_FormatEx(fmt) {
+        if (!event.value)
+            return;
+        // Try parsing the current value as a date
+        const d = new Date(event.value);
+        if (isNaN(d.getTime()))
+            return;
+        event.value = printd(fmt, d);
+    }
+    function AFDate_KeystrokeEx(fmt) {
+        if (event.willCommit) {
+            if (!event.value)
+                return;
+            const d = scand(fmt, event.value);
+            if (!d) {
+                event.rc = false;
+            }
+        }
+        // On non-commit keystrokes, allow all input
+    }
+    function AFNumber_Format(nDec, sepStyle, negStyle, _currStyle, strCurrency, bCurrencyPrepend) {
+        if (!event.value && event.value !== '0')
+            return;
+        const num = parseNumericValue(event.value);
+        event.value = formatNumber(num, nDec, sepStyle, negStyle, _currStyle, strCurrency, bCurrencyPrepend);
+    }
+    function AFNumber_Keystroke(nDec, _sepStyle, _negStyle, _currStyle, _strCurrency, _bCurrencyPrepend) {
+        if (event.willCommit) {
+            if (!event.value)
+                return;
+            const num = parseFloat(event.value);
+            if (isNaN(num)) {
+                event.rc = false;
+                return;
+            }
+            // Check decimal places
+            const parts = event.value.split('.');
+            if (nDec === 0 && parts.length > 1) {
+                event.rc = false;
+            }
+        }
+    }
+    function AFSimple_Calculate(op, fields) {
+        if (!getFieldValue)
+            return;
+        const values = fields.map((name) => parseNumericValue(getFieldValue(name)));
+        let result;
+        switch (op.toUpperCase()) {
+            case 'SUM':
+                result = values.reduce((a, b) => a + b, 0);
+                break;
+            case 'AVG':
+                result = values.length
+                    ? values.reduce((a, b) => a + b, 0) / values.length
+                    : 0;
+                break;
+            case 'PRD':
+                result = values.reduce((a, b) => a * b, 1);
+                break;
+            case 'MIN':
+                result = values.length ? Math.min(...values) : 0;
+                break;
+            case 'MAX':
+                result = values.length ? Math.max(...values) : 0;
+                break;
+            default:
+                return;
+        }
+        event.value = String(result);
+    }
+    function AFSpecial_Format(psf) {
+        if (!event.value)
+            return;
+        const digits = event.value.replace(/\D/g, '');
+        switch (psf) {
+            case 0: // zip: 12345
+                event.value = digits.slice(0, 5).padEnd(5, '0');
+                break;
+            case 1: // ssn: 123-45-6789
+                event.value =
+                    digits.slice(0, 3) +
+                        '-' +
+                        digits.slice(3, 5) +
+                        '-' +
+                        digits.slice(5, 9);
+                break;
+            case 2: // phone: (123) 456-7890
+                event.value =
+                    '(' +
+                        digits.slice(0, 3) +
+                        ') ' +
+                        digits.slice(3, 6) +
+                        '-' +
+                        digits.slice(6, 10);
+                break;
+            case 3: // zip+4: 12345-6789
+                event.value = digits.slice(0, 5) + '-' + digits.slice(5, 9);
+                break;
+        }
+    }
+    function AFSpecial_Keystroke(psf) {
+        if (!event.willCommit)
+            return;
+        if (!event.value)
+            return;
+        const digits = event.value.replace(/\D/g, '');
+        switch (psf) {
+            case 0: // zip
+                if (digits.length !== 5)
+                    event.rc = false;
+                break;
+            case 1: // ssn
+                if (digits.length !== 9)
+                    event.rc = false;
+                break;
+            case 2: // phone
+                if (digits.length !== 10 && digits.length !== 7)
+                    event.rc = false;
+                break;
+            case 3: // zip+4
+                if (digits.length !== 9)
+                    event.rc = false;
+                break;
+        }
+    }
+    return {
+        util,
+        AFDate_FormatEx,
+        AFDate_KeystrokeEx,
+        AFNumber_Format,
+        AFNumber_Keystroke,
+        AFSimple_Calculate,
+        AFSpecial_Format,
+        AFSpecial_Keystroke,
+    };
+}

package/dist/acroform/js/pdf-js-engine-impl.d.ts

@@ -0,0 +1,18 @@
+import type { PdfJsEngine, PdfJsEvent } from './pdf-js-engine.js';
+export interface PdfJavaScriptEngineOptions {
+    getFieldValue?: (name: string) => string;
+}
+/**
+ * Default JavaScript engine that executes PDF JS actions via `new Function()`.
+ *
+ * **Security note:** This engine runs PDF-sourced JavaScript with access to the
+ * ambient JS environment (e.g. `globalThis`, constructors, network APIs). It is
+ * NOT sandboxed and should only be used with trusted PDF documents. For untrusted
+ * documents, provide your own `PdfJsEngine` implementation that evaluates code
+ * in an isolated context (e.g. Node `vm`, a dedicated realm, or a Web Worker).
+ */
+export declare class PdfJavaScriptEngine implements PdfJsEngine {
+    private _getFieldValue?;
+    constructor(options?: PdfJavaScriptEngineOptions);
+    execute(code: string, event: PdfJsEvent): void;
+}

package/dist/acroform/js/pdf-js-engine-impl.js

@@ -0,0 +1,22 @@
+import { createBuiltins } from './pdf-js-builtins.js';
+/**
+ * Default JavaScript engine that executes PDF JS actions via `new Function()`.
+ *
+ * **Security note:** This engine runs PDF-sourced JavaScript with access to the
+ * ambient JS environment (e.g. `globalThis`, constructors, network APIs). It is
+ * NOT sandboxed and should only be used with trusted PDF documents. For untrusted
+ * documents, provide your own `PdfJsEngine` implementation that evaluates code
+ * in an isolated context (e.g. Node `vm`, a dedicated realm, or a Web Worker).
+ */
+export class PdfJavaScriptEngine {
+    _getFieldValue;
+    constructor(options) {
+        this._getFieldValue = options?.getFieldValue;
+    }
+    execute(code, event) {
+        const builtins = createBuiltins(event, this._getFieldValue);
+        const names = Object.keys(builtins);
+        const fn = new Function('event', 'app', ...names, code);
+        fn(event, Object.freeze({ alert() { } }), ...names.map((k) => builtins[k]));
+    }
+}

package/dist/acroform/js/pdf-js-engine.d.ts

@@ -0,0 +1,10 @@
+export interface PdfJsEvent {
+    fieldName: string;
+    value: string;
+    willCommit?: boolean;
+    rc: boolean;
+    changeEx?: string;
+}
+export interface PdfJsEngine {
+    execute(code: string, event: PdfJsEvent): void;
+}

package/dist/acroform/js/pdf-js-engine.js

@@ -0,0 +1 @@
+export {};

package/dist/acroform/pdf-acro-form.d.ts

@@ -12,6 +12,7 @@ import './fields/pdf-choice-form-field.js';
 import './fields/pdf-signature-form-field.js';
 import { PdfDefaultResourcesDictionary } from '../annotations/pdf-default-resources.js';
 import { PdfXfaForm } from './xfa/pdf-xfa-form.js';
+import type { PdfJsEngine } from './js/pdf-js-engine.js';
 export declare class PdfAcroForm<T extends Record<string, string> = Record<string, string>> extends PdfIndirectObject<PdfDictionary<{
     Fields: PdfArray<PdfObjectReference> | PdfObjectReference;
     NeedAppearances?: PdfBoolean;
@@ -38,7 +39,10 @@ export declare class PdfAcroForm<T extends Record<string, string> = Record<strin
     set fields(newFields: PdfFormField[]);
     setValues(values: Partial<T>): void;
     importData(fields: T): void;
+    private _fireValidate;
+    private _fireCalculate;
     exportData(): Partial<T>;
+    jsEngine?: PdfJsEngine;
     fontEncodingMaps: Map<string, Map<number, string>>;
     getFontEncodingMap(fontName: string): Map<number, string> | null;
     get xfa(): PdfXfaForm | null;

package/dist/acroform/pdf-acro-form.js

@@ -122,15 +122,70 @@ export class PdfAcroForm extends PdfIndirectObject {
         for (const field of this.fields) {
             const name = field.name;
             if (name in values && values[name] !== undefined) {
-                field.value = values[name];
+                const result = this._fireValidate(field, values[name]);
+                if (!result.rc)
+                    continue;
+                field.value = result.value;
             }
         }
+        this._fireCalculate();
     }
     importData(fields) {
         for (const field of this.fields) {
             const name = field.name;
             if (name && name in fields) {
-                field.value = fields[name];
+                const result = this._fireValidate(field, fields[name]);
+                if (!result.rc)
+                    continue;
+                field.value = result.value;
+            }
+        }
+        this._fireCalculate();
+    }
+    _fireValidate(field, value) {
+        const validateAction = field.actions?.validate;
+        if (!validateAction?.code)
+            return { rc: true, value };
+        const event = {
+            fieldName: field.name,
+            value,
+            willCommit: true,
+            rc: true,
+        };
+        validateAction.execute(event);
+        return { rc: event.rc, value: event.value };
+    }
+    _fireCalculate() {
+        const co = this.content.get('CO');
+        if (!(co instanceof PdfArray))
+            return;
+        const allFields = this.fields;
+        const fieldsByObjNum = new Map();
+        for (const field of allFields) {
+            if (field.objectNumber != null) {
+                fieldsByObjNum.set(field.objectNumber, field);
+            }
+        }
+        for (const item of co.items) {
+            if (!(item instanceof PdfObjectReference))
+                continue;
+            const resolved = item.resolve();
+            if (!resolved)
+                continue;
+            const field = fieldsByObjNum.get(resolved.objectNumber);
+            if (!field)
+                continue;
+            const calcAction = field.actions?.calculate;
+            if (!calcAction?.code)
+                continue;
+            const event = {
+                fieldName: field.name,
+                value: field.value,
+                rc: true,
+            };
+            calcAction.execute(event);
+            if (event.rc && event.value !== field.value) {
+                field.value = event.value;
             }
         }
     }
@@ -144,6 +199,7 @@ export class PdfAcroForm extends PdfIndirectObject {
         }
         return result;
     }
+    jsEngine;
     fontEncodingMaps = new Map();
     getFontEncodingMap(fontName) {
         if (this.fontEncodingMaps.has(fontName)) {

package/dist/annotations/pdf-annotation.d.ts

@@ -34,6 +34,26 @@ export declare class PdfAnnotation extends PdfIndirectObject<PdfDictionary<{
     AP?: PdfAppearanceStreamDictionary;
     P?: PdfObjectReference;
     Parent?: PdfObjectReference<PdfPage>;
+    A?: PdfDictionary<{
+        Type?: PdfName;
+        S?: PdfName;
+        D?: PdfArray | PdfDictionary;
+        T?: PdfString;
+        F?: PdfNumber;
+        Win?: PdfDictionary;
+        JS?: PdfString;
+    }>;
+    AA?: PdfDictionary<{
+        D?: PdfObjectReference | PdfDictionary;
+        U?: PdfObjectReference | PdfDictionary;
+        Fo?: PdfObjectReference | PdfDictionary;
+        Bl?: PdfObjectReference | PdfDictionary;
+        PO?: PdfObjectReference | PdfDictionary;
+        K?: PdfObjectReference | PdfDictionary;
+        V?: PdfObjectReference | PdfDictionary;
+        C?: PdfObjectReference | PdfDictionary;
+        F?: PdfObjectReference | PdfDictionary;
+    }>;
 }>> {
     private _annotationFlags?;
     private get flags_();

package/dist/core/objects/pdf-dictionary.d.ts

@@ -22,6 +22,8 @@ export declare class PdfDictionary<T extends PdfDictionaryEntries = PdfDictionar
     entries(): IterableIterator<[string, PdfObject | undefined]>;
     get isTrailingDelimited(): boolean;
     protected tokenize(): PdfToken[];
+    /** Factory-style type conversion: constructs a new instance passing `this` as the first argument */
+    becomes<U extends PdfDictionary, A extends unknown[]>(cls: new (source: PdfDictionary, ...args: A) => U, ...args: A): U;
     copyFrom(other: PdfDictionary<any>): void;
     cloneImpl(): this;
     setModified(modified?: boolean): void;

package/dist/core/objects/pdf-dictionary.js

@@ -131,6 +131,20 @@ export class PdfDictionary extends PdfObject {
             new PdfEndDictionaryToken(),
         ];
     }
+    /** Factory-style type conversion: constructs a new instance passing `this` as the first argument */
+    becomes(cls, ...args) {
+        if (this instanceof cls)
+            return this;
+        const donor = new cls(this, ...args);
+        Object.setPrototypeOf(this, cls.prototype);
+        for (const key of Object.getOwnPropertyNames(donor)) {
+            if (!Object.prototype.hasOwnProperty.call(this, key)) {
+                ;
+                this[key] = donor[key];
+            }
+        }
+        return this;
+    }
     copyFrom(other) {
         for (const [key, value] of other.#entries) {
             this.#entries.set(key, value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdf-lite",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "main": "dist/index.js",
   "type": "module",
   "exports": {