pdf-lite 1.3.3 → 1.5.0

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

@@ -0,0 +1,433 @@
+import { PdfDictionary } from '../../core/objects/pdf-dictionary.js';
+import { PdfArray } from '../../core/objects/pdf-array.js';
+import { PdfString } from '../../core/objects/pdf-string.js';
+import { PdfName } from '../../core/objects/pdf-name.js';
+import { PdfNumber } from '../../core/objects/pdf-number.js';
+import { decodeWithFontEncoding } from '../../utils/decodeWithFontEncoding.js';
+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';
+/**
+ * Abstract base form field class. Extends PdfWidgetAnnotation with form-specific properties:
+ * FT, V, DA, Ff, T (name), field hierarchy (parent/children/siblings).
+ * Subclasses must implement generateAppearance().
+ */
+export class PdfFormField extends PdfWidgetAnnotation {
+    _parent;
+    defaultGenerateAppearance = true;
+    _appearanceStream;
+    _appearanceStreamYes;
+    form;
+    constructor(options) {
+        super({ other: options?.other });
+        this.form = options?.form;
+        if (options?.parent) {
+            this._parent = options.parent;
+        }
+    }
+    get parent() {
+        if (this._parent)
+            return this._parent;
+        if (!this.form)
+            return undefined;
+        return this.form.fields.find((f) => f !== this &&
+            f.kids.some((k) => k.objectNumber === this.objectNumber &&
+                k.generationNumber === this.generationNumber));
+    }
+    set parent(field) {
+        if (this._parent) {
+            this._parent.kids = this._parent.kids.filter((k) => k.objectNumber !== this.objectNumber ||
+                k.generationNumber !== this.generationNumber);
+        }
+        this._parent = field;
+        if (field) {
+            const alreadyInKids = field.kids.some((k) => k.objectNumber === this.objectNumber &&
+                k.generationNumber === this.generationNumber);
+            if (!alreadyInKids) {
+                field.kids = [...field.kids, this.reference];
+            }
+        }
+    }
+    get children() {
+        if (!this.form)
+            return [];
+        return this.form.fields.filter((f) => f.parent === this);
+    }
+    set children(fields) {
+        for (const child of this.children) {
+            child._parent = undefined;
+        }
+        this.kids = fields.map((f) => f.reference);
+        for (const child of fields) {
+            child._parent = this;
+        }
+    }
+    get siblings() {
+        return this.parent?.children ?? [];
+    }
+    get encodingMap() {
+        const fontName = this.fontName;
+        if (!fontName)
+            return undefined;
+        return this.form?.fontEncodingMaps?.get(fontName);
+    }
+    get fieldType() {
+        const ft = this.content.get('FT')?.as(PdfName)?.value ??
+            this.parent?.content.get('FT')?.as(PdfName)?.value;
+        switch (ft) {
+            case 'Tx':
+                return 'Text';
+            case 'Btn':
+                return 'Button';
+            case 'Ch':
+                return 'Choice';
+            case 'Sig':
+                return 'Signature';
+            default:
+                return null;
+        }
+    }
+    set fieldType(type) {
+        if (type === null) {
+            this.content.delete('FT');
+        }
+        else {
+            this.content.set('FT', new PdfName(PdfFieldTypeConst[type]));
+        }
+    }
+    get name() {
+        const parentName = this.parent?.name ?? '';
+        const ownName = this.content.get('T')?.as(PdfString)?.value ?? '';
+        if (parentName && ownName) {
+            return `${parentName}.${ownName}`;
+        }
+        return parentName || ownName;
+    }
+    set name(name) {
+        this.content.set('T', new PdfString(name));
+    }
+    get defaultValue() {
+        const dv = this.content.get('DV') ?? this.parent?.content.get('DV');
+        if (dv instanceof PdfString)
+            return dv.value;
+        if (dv instanceof PdfName)
+            return dv.value;
+        return '';
+    }
+    set defaultValue(val) {
+        this.content.set('DV', new PdfString(val));
+    }
+    get value() {
+        const v = this.content.get('V') ?? this.parent?.content.get('V');
+        if (v instanceof PdfString) {
+            if (v.isUTF16BE)
+                return v.value;
+            if (this.encodingMap) {
+                return decodeWithFontEncoding(v.raw, this.encodingMap);
+            }
+            return v.value;
+        }
+        else if (v instanceof PdfName) {
+            return v.value;
+        }
+        return '';
+    }
+    set value(val) {
+        if (this.value === val)
+            return;
+        const fieldParent = this.parent?.content.get('FT')
+            ? this.parent
+            : undefined;
+        const generateAppearance = this._storeValue(val, fieldParent);
+        if (generateAppearance && this.defaultGenerateAppearance) {
+            this.tryGenerateAppearance(this);
+            for (const sibling of this.siblings) {
+                if (sibling !== this &&
+                    sibling.rect &&
+                    sibling.defaultGenerateAppearance) {
+                    this.tryGenerateAppearance(sibling);
+                }
+            }
+        }
+    }
+    /**
+     * Writes the value to the dictionary. Returns true if appearance generation
+     * should proceed, false to skip it (e.g. when value was cleared).
+     * Override in subclasses to change the stored representation.
+     */
+    _storeValue(val, fieldParent) {
+        const pdfVal = val instanceof PdfString ? val : new PdfString(val);
+        this.content.set('V', pdfVal);
+        fieldParent?.content.set('V', pdfVal);
+        return true;
+    }
+    tryGenerateAppearance(field) {
+        field.generateAppearance();
+    }
+    get checked() {
+        return false;
+    }
+    set checked(_isChecked) {
+        // no-op for non-button fields; overridden in PdfButtonFormField
+    }
+    get fontSize() {
+        const da = this.defaultAppearance || '';
+        const parsed = PdfDefaultAppearance.parse(da);
+        return parsed?.fontSize ?? null;
+    }
+    set fontSize(size) {
+        const da = this.defaultAppearance || '';
+        if (!da) {
+            this.content.set('DA', new PdfDefaultAppearance('F1', size, '0 g'));
+            return;
+        }
+        const parsed = PdfDefaultAppearance.parse(da);
+        if (parsed) {
+            parsed.fontSize = size;
+            this.content.set('DA', parsed);
+        }
+    }
+    get fontName() {
+        const da = this.defaultAppearance || '';
+        const parsed = PdfDefaultAppearance.parse(da);
+        return parsed?.fontName ?? null;
+    }
+    set fontName(fontName) {
+        const da = this.defaultAppearance || '';
+        if (!da) {
+            this.content.set('DA', new PdfDefaultAppearance(fontName, 12, '0 g'));
+            return;
+        }
+        const parsed = PdfDefaultAppearance.parse(da);
+        if (parsed) {
+            parsed.fontName = fontName;
+            this.content.set('DA', parsed);
+        }
+    }
+    set font(font) {
+        if (font === null) {
+            this.content.set('DA', new PdfString(''));
+            return;
+        }
+        const resourceName = font.resourceName;
+        const currentSize = this.fontSize ?? 12;
+        const da = this.defaultAppearance || '';
+        if (!da) {
+            this.content.set('DA', new PdfDefaultAppearance(resourceName, currentSize, '0 g'));
+            return;
+        }
+        const parsed = PdfDefaultAppearance.parse(da);
+        if (parsed) {
+            parsed.fontName = resourceName;
+            this.content.set('DA', parsed);
+        }
+    }
+    get flags() {
+        const flags = new PdfFormFieldFlags(this.content.get('Ff') ?? this.parent?.content.get('Ff') ?? 0);
+        flags.onChange(() => {
+            this.flags = flags;
+        });
+        return flags;
+    }
+    set flags(v) {
+        this.content.set('Ff', v);
+    }
+    get readOnly() {
+        return this.flags.readOnly;
+    }
+    set readOnly(v) {
+        this.flags.readOnly = v;
+    }
+    get required() {
+        return this.flags.required;
+    }
+    set required(v) {
+        this.flags.required = v;
+    }
+    get multiline() {
+        return this.flags.multiline;
+    }
+    set multiline(v) {
+        this.flags.multiline = v;
+    }
+    get password() {
+        return this.flags.password;
+    }
+    set password(v) {
+        this.flags.password = v;
+    }
+    get comb() {
+        return this.flags.comb;
+    }
+    get combField() {
+        return this.flags.comb;
+    }
+    set combField(v) {
+        this.flags.comb = v;
+    }
+    get combo() {
+        return this.flags.combo;
+    }
+    set combo(v) {
+        this.flags.combo = v;
+    }
+    get radio() {
+        return this.flags.radio;
+    }
+    set radio(v) {
+        this.flags.radio = v;
+    }
+    get noToggleToOff() {
+        return this.flags.noToggleToOff;
+    }
+    set noToggleToOff(v) {
+        this.flags.noToggleToOff = v;
+    }
+    get noExport() {
+        return this.flags.noExport;
+    }
+    set noExport(v) {
+        this.flags.noExport = v;
+    }
+    get pushButton() {
+        return this.flags.pushButton;
+    }
+    set pushButton(v) {
+        this.flags.pushButton = v;
+    }
+    get edit() {
+        return this.flags.edit;
+    }
+    set edit(v) {
+        this.flags.edit = v;
+    }
+    get sort() {
+        return this.flags.sort;
+    }
+    set sort(v) {
+        this.flags.sort = v;
+    }
+    get multiSelect() {
+        return this.flags.multiSelect;
+    }
+    set multiSelect(v) {
+        this.flags.multiSelect = v;
+    }
+    get doNotSpellCheck() {
+        return this.flags.doNotSpellCheck;
+    }
+    set doNotSpellCheck(v) {
+        this.flags.doNotSpellCheck = v;
+    }
+    get doNotScroll() {
+        return this.flags.doNotScroll;
+    }
+    set doNotScroll(v) {
+        this.flags.doNotScroll = v;
+    }
+    get commitOnSelChange() {
+        return this.flags.commitOnSelChange;
+    }
+    set commitOnSelChange(v) {
+        this.flags.commitOnSelChange = v;
+    }
+    get quadding() {
+        return (this.content.get('Q')?.as(PdfNumber)?.value ??
+            this.parent?.content.get('Q')?.as(PdfNumber)?.value ??
+            0);
+    }
+    set quadding(q) {
+        this.content.set('Q', new PdfNumber(q));
+    }
+    get defaultAppearance() {
+        return (this.content.get('DA')?.as(PdfString)?.value ??
+            this.parent?.content.get('DA')?.as(PdfString)?.value ??
+            this.form?.defaultAppearance ??
+            null);
+    }
+    set defaultAppearance(da) {
+        this.content.set('DA', new PdfString(da));
+    }
+    get maxLen() {
+        return this.content.get('MaxLen')?.as(PdfNumber)?.value ?? null;
+    }
+    set maxLen(maxLen) {
+        if (maxLen === null) {
+            this.content.delete('MaxLen');
+        }
+        else {
+            this.content.set('MaxLen', new PdfNumber(maxLen));
+        }
+    }
+    get kids() {
+        const kidsArray = this.content
+            .get('Kids')
+            ?.as((PdfArray));
+        if (!kidsArray)
+            return [];
+        return kidsArray.items;
+    }
+    set kids(kids) {
+        if (kids.length === 0) {
+            this.content.delete('Kids');
+            return;
+        }
+        const kidsArray = new PdfArray(kids);
+        this.content.set('Kids', kidsArray);
+    }
+    getAppearanceStream() {
+        return this._appearanceStream?.content;
+    }
+    getAppearanceStreamsForWriting() {
+        if (!this._appearanceStream)
+            return undefined;
+        return { primary: this._appearanceStream };
+    }
+    setAppearanceReference(appearanceStreamRef, _appearanceStreamYesRef) {
+        let apDict = this.appearanceStreamDict;
+        if (!apDict) {
+            apDict = new PdfDictionary();
+            this.appearanceStreamDict = apDict;
+        }
+        apDict.set('N', appearanceStreamRef);
+    }
+    static _fallbackCtor;
+    static _registry = new Map();
+    static registerFieldType(ft, ctor, options) {
+        PdfFormField._registry.set(ft, ctor);
+        if (options?.fallback) {
+            PdfFormField._fallbackCtor = ctor;
+        }
+    }
+    static create(options) {
+        let ft;
+        try {
+            const dict = options.other.content.as(PdfDictionary);
+            ft = dict.get('FT')?.as(PdfName)?.value;
+        }
+        catch {
+            // content may not be a dictionary
+        }
+        if (!ft && options.parent) {
+            try {
+                ft = options.parent.content.get('FT')?.as(PdfName)?.value;
+            }
+            catch {
+                // ignore
+            }
+        }
+        const Ctor = ft ? PdfFormField._registry.get(ft) : undefined;
+        if (!Ctor) {
+            // Fields without FT are parent/container nodes — use the
+            // fallback type (typically Text) as a concrete stand-in.
+            if (!PdfFormField._fallbackCtor) {
+                throw new Error(`Unknown field type: ${ft ?? '(none)'}`);
+            }
+            return new PdfFormField._fallbackCtor(options);
+        }
+        return new Ctor(options);
+    }
+}
+/** Backward compatible alias */
+export { PdfFormField as PdfAcroFormField };

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

@@ -0,0 +1,7 @@
+import { PdfFormField } from './pdf-form-field.js';
+/**
+ * Signature form field subtype.
+ */
+export declare class PdfSignatureFormField extends PdfFormField {
+    generateAppearance(): boolean;
+}

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

@@ -0,0 +1,12 @@
+import { PdfFormField } from './pdf-form-field.js';
+/**
+ * Signature form field subtype.
+ */
+export class PdfSignatureFormField extends PdfFormField {
+    static {
+        PdfFormField.registerFieldType('Sig', PdfSignatureFormField);
+    }
+    generateAppearance() {
+        return false;
+    }
+}

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

@@ -0,0 +1,10 @@
+import { PdfFormField } from './pdf-form-field.js';
+/**
+ * Text form field subtype.
+ */
+export declare class PdfTextFormField extends PdfFormField {
+    generateAppearance(options?: {
+        makeReadOnly?: boolean;
+        textYOffset?: number;
+    }): boolean;
+}

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

@@ -0,0 +1,77 @@
+import { PdfFormField } from './pdf-form-field.js';
+import { PdfDefaultAppearance } from './pdf-default-appearance.js';
+import { PdfTextAppearanceStream } from '../appearance/pdf-text-appearance-stream.js';
+import { PdfDictionary } from '../../core/objects/pdf-dictionary.js';
+import { PdfObjectReference } from '../../core/objects/pdf-object-reference.js';
+/**
+ * Text form field subtype.
+ */
+export class PdfTextFormField extends PdfFormField {
+    static {
+        PdfFormField.registerFieldType('Tx', PdfTextFormField, {
+            fallback: true,
+        });
+    }
+    generateAppearance(options) {
+        const rect = this.rect;
+        if (!rect || rect.length !== 4)
+            return false;
+        const da = this.defaultAppearance;
+        if (!da)
+            return false;
+        const parsed = PdfDefaultAppearance.parse(da);
+        if (!parsed)
+            return false;
+        let fontResources;
+        const drFontValue = this.form?.defaultResources?.get('Font');
+        const drFonts = drFontValue instanceof PdfDictionary ? drFontValue : undefined;
+        const daFontRef = this.form?.fontRefs?.get(parsed.fontName);
+        if (drFonts || daFontRef) {
+            // Build a fresh font dict using clean PdfObjectReferences (no
+            // pre/postTokens inherited from the original parse context).
+            const fontDict = new PdfDictionary();
+            if (drFonts) {
+                for (const [key, val] of drFonts.entries()) {
+                    if (val instanceof PdfObjectReference) {
+                        fontDict.set(key, new PdfObjectReference(val.objectNumber, val.generationNumber));
+                    }
+                    else if (val != null) {
+                        fontDict.set(key, val);
+                    }
+                }
+            }
+            if (daFontRef && !fontDict.has(parsed.fontName)) {
+                fontDict.set(parsed.fontName, new PdfObjectReference(daFontRef.objectNumber, daFontRef.generationNumber));
+            }
+            fontResources = new PdfDictionary();
+            fontResources.set('Font', fontDict);
+        }
+        const isUnicode = this.form?.isFontUnicode(parsed.fontName) ?? false;
+        const encodingMap = this.form?.fontEncodingMaps?.get(parsed.fontName);
+        const reverseEncodingMap = encodingMap
+            ? new Map(Array.from(encodingMap, ([code, char]) => [char, code]))
+            : undefined;
+        this._appearanceStream = new PdfTextAppearanceStream({
+            rect: rect,
+            value: this.value,
+            da: parsed,
+            multiline: this.multiline,
+            comb: this.comb,
+            maxLen: this.maxLen,
+            fontResources,
+            isUnicode,
+            reverseEncodingMap,
+        });
+        if (options?.makeReadOnly) {
+            this.readOnly = true;
+            if (!this.print)
+                this.print = true;
+            this.noZoom = true;
+        }
+        else {
+            if (!this.print)
+                this.print = true;
+        }
+        return true;
+    }
+}

package/dist/acroform/fields/types.d.ts

@@ -0,0 +1,26 @@
+import type { PdfDefaultResourcesDictionary } from '../acroform.js';
+import type { PdfObjectReference } from '../../core/objects/pdf-object-reference.js';
+/**
+ * Field types for AcroForm fields
+ */
+export declare const PdfFieldType: {
+    readonly Text: "Tx";
+    readonly Button: "Btn";
+    readonly Choice: "Ch";
+    readonly Signature: "Sig";
+};
+export type PdfFieldType = keyof typeof PdfFieldType;
+/**
+ * Interface that PdfAcroForm implements, used by PdfFormField to avoid circular imports.
+ * Uses generic field type to avoid circular dependency.
+ */
+export interface FormContext<TField = any> {
+    defaultResources: PdfDefaultResourcesDictionary | null;
+    defaultAppearance: string | null;
+    fontEncodingMaps: Map<string, Map<number, string>>;
+    /** Object references for all resolved fonts, keyed by resource name. */
+    fontRefs: Map<string, PdfObjectReference>;
+    fields: TField[];
+    isFontUnicode: (fontName: string) => boolean;
+    needAppearances: boolean;
+}

package/dist/acroform/fields/types.js

@@ -0,0 +1,9 @@
+/**
+ * Field types for AcroForm fields
+ */
+export const PdfFieldType = {
+    Text: 'Tx',
+    Button: 'Btn',
+    Choice: 'Ch',
+    Signature: 'Sig',
+};

package/dist/acroform/index.d.ts

@@ -1,2 +1,6 @@
 export * from './manager.js';
-export * from './acroform.js';
+export * from './pdf-acro-form.js';
+export * from './fields/index.js';
+export * from './appearance/index.js';
+export * from './xfa/index.js';
+export { PdfFontEncodingCache } from './pdf-font-encoding-cache.js';

package/dist/acroform/index.js

@@ -1,2 +1,6 @@
 export * from './manager.js';
-export * from './acroform.js';
+export * from './pdf-acro-form.js';
+export * from './fields/index.js';
+export * from './appearance/index.js';
+export * from './xfa/index.js';
+export { PdfFontEncodingCache } from './pdf-font-encoding-cache.js';

package/dist/acroform/manager.d.ts

@@ -1,12 +1,19 @@
 import { PdfDocument } from '../pdf/pdf-document.js';
 import { PdfAcroForm } from './acroform.js';
+import { PdfXfaForm } from './xfa/pdf-xfa-form.js';
 /**
  * Manages AcroForm fields in PDF documents.
  * Provides methods to read and write form field values.
  */
 export declare class PdfAcroFormManager {
     private document;
+    private _acroform;
     constructor(document: PdfDocument);
+    /**
+     * Gets the XFA form wrapper, loading it lazily on first access.
+     * @returns The PdfXfaForm or null if no XFA forms exist
+     */
+    getXfa(): Promise<PdfXfaForm | null>;
     /**
      * Checks if the document contains AcroForm fields.
      * @returns True if the document has AcroForm fields, false otherwise
@@ -17,10 +24,14 @@ export declare class PdfAcroFormManager {
      * @returns The AcroForm object or null if not found
      */
     read(): Promise<PdfAcroForm | null>;
+    /**
+     * Explicitly sets the XFA form instance, bypassing the lazy load on next write.
+     */
+    setXfa(xfa: PdfXfaForm): Promise<void>;
     /**
      * Writes the provided AcroForm to the associated PDF document.
      * @param acroForm The AcroForm instance to serialize into the document.
      * @throws Error If writing the AcroForm to the document fails.
      */
-    write(acroForm: PdfAcroForm): Promise<void>;
+    write(acroForm?: PdfAcroForm): Promise<void>;
 }

package/dist/acroform/manager.js

@@ -5,9 +5,17 @@ import { PdfAcroForm } from './acroform.js';
  */
 export class PdfAcroFormManager {
     document;
+    _acroform = null;
     constructor(document) {
         this.document = document;
     }
+    /**
+     * Gets the XFA form wrapper, loading it lazily on first access.
+     * @returns The PdfXfaForm or null if no XFA forms exist
+     */
+    async getXfa() {
+        return (await (await this.read())?.getXfa()) || null;
+    }
     /**
      * Checks if the document contains AcroForm fields.
      * @returns True if the document has AcroForm fields, false otherwise
@@ -26,7 +34,17 @@ export class PdfAcroFormManager {
      * @returns The AcroForm object or null if not found
      */
     async read() {
-        return await PdfAcroForm.fromDocument(this.document);
+        if (this._acroform)
+            return this._acroform;
+        this._acroform = await PdfAcroForm.fromDocument(this.document);
+        return this._acroform;
+    }
+    /**
+     * Explicitly sets the XFA form instance, bypassing the lazy load on next write.
+     */
+    async setXfa(xfa) {
+        ;
+        (await this.read())?.setXfa(xfa);
     }
     /**
      * Writes the provided AcroForm to the associated PDF document.
@@ -34,6 +52,6 @@ export class PdfAcroFormManager {
      * @throws Error If writing the AcroForm to the document fails.
      */
     async write(acroForm) {
-        await acroForm.write(this.document);
+        await (acroForm ?? (await this.read()))?.write(this.document);
     }
 }