pdf-lite 1.4.0 → 1.6.0

package/dist/acroform/fields/{PdfFormField.d.ts → pdf-form-field.d.ts}

@@ -1,33 +1,43 @@
+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 { PdfObjectReference } from '../../core/objects/pdf-object-reference.js';
 import { PdfIndirectObject } from '../../core/objects/pdf-indirect-object.js';
 import { PdfFont } from '../../fonts/pdf-font.js';
 import { PdfStream } from '../../core/objects/pdf-stream.js';
-import { PdfWidgetAnnotation } from '../../annotations/PdfWidgetAnnotation.js';
-import type { PdfAppearanceStream } from '../appearance/PdfAppearanceStream.js';
-import type { FormContext, PdfFieldType } from './types.js';
+import { PdfWidgetAnnotation } from '../../annotations/pdf-widget-annotation.js';
+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';
 /**
  * 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 declare abstract class PdfFormField extends PdfWidgetAnnotation {
-    private _parent?;
     defaultGenerateAppearance: boolean;
-    protected _appearanceStream?: PdfAppearanceStream;
-    protected _appearanceStreamYes?: PdfAppearanceStream;
-    form?: FormContext<PdfFormField>;
-    constructor(options?: {
-        other?: PdfIndirectObject;
-        form?: FormContext<PdfFormField>;
-        parent?: PdfFormField;
+    /** @internal */
+    _form?: PdfAcroForm;
+    constructor(other?: PdfIndirectObject | {
+        form?: PdfAcroForm;
     });
+    set form(f: PdfAcroForm);
+    static create(other?: PdfIndirectObject): PdfFormField;
     get parent(): PdfFormField | undefined;
-    set parent(field: PdfFormField | undefined);
+    set parent(field: PdfFormField | PdfIndirectObject | undefined);
     get children(): PdfFormField[];
     set children(fields: PdfFormField[]);
     get siblings(): PdfFormField[];
-    get encodingMap(): Map<number, string> | undefined;
+    get font(): PdfFont | null;
+    get defaultResources(): PdfDefaultResourcesDictionary | null;
+    set defaultResources(resources: PdfDefaultResourcesDictionary | null);
+    /**
+     * Builds a Resources dictionary containing the font entry for `fontName`,
+     * resolved from DR (handling indirect references) or from a loaded font.
+     * Returns undefined if neither source provides the font.
+     */
+    buildFontResources(fontName: string): PdfDictionary | undefined;
     get fieldType(): PdfFieldType | null;
     set fieldType(type: PdfFieldType | null);
     get name(): string;
@@ -36,17 +46,19 @@ export declare abstract class PdfFormField extends PdfWidgetAnnotation {
     set defaultValue(val: string);
     get value(): string;
     set value(val: string | PdfString);
-    get checked(): boolean;
-    set checked(isChecked: boolean);
+    /**
+     * 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.
+     */
+    protected _storeValue(val: string | PdfString, fieldParent: PdfFormField | undefined): boolean;
     get fontSize(): number | null;
     set fontSize(size: number);
     get fontName(): string | null;
     set fontName(fontName: string);
     set font(font: PdfFont | null);
-    get flags(): number;
-    set flags(flags: number);
-    private getFlag;
-    private setFlag;
+    get flags(): PdfFormFieldFlags;
+    set flags(v: PdfFormFieldFlags);
     get readOnly(): boolean;
     set readOnly(v: boolean);
     get required(): boolean;
@@ -82,38 +94,25 @@ export declare abstract class PdfFormField extends PdfWidgetAnnotation {
     set commitOnSelChange(v: boolean);
     get quadding(): number;
     set quadding(q: number);
-    get options(): string[];
-    set options(options: string[]);
     get defaultAppearance(): string | null;
     set defaultAppearance(da: string);
     get maxLen(): number | null;
     set maxLen(maxLen: number | null);
-    get kids(): PdfObjectReference[];
+    get kids(): PdfArray<PdfObjectReference> | undefined;
     set kids(kids: PdfObjectReference[]);
     abstract generateAppearance(options?: {
         makeReadOnly?: boolean;
         textYOffset?: number;
     }): boolean;
-    getAppearanceStream(): PdfStream | undefined;
-    getAppearanceStreamsForWriting(): {
-        primary: PdfAppearanceStream;
-        secondary?: PdfAppearanceStream;
-    } | undefined;
-    setAppearanceReference(appearanceStreamRef: PdfObjectReference, appearanceStreamYesRef?: PdfObjectReference): void;
+    setAppearanceStream(stream: PdfIndirectObject | {
+        [key: string]: PdfIndirectObject;
+    }): void;
+    getAppearanceStream(setting?: string): PdfIndirectObject<PdfStream> | null;
     private static _fallbackCtor?;
     private static _registry;
-    static registerFieldType(ft: string, ctor: new (options?: {
-        other?: PdfIndirectObject;
-        form?: FormContext<PdfFormField>;
-        parent?: PdfFormField;
-    }) => PdfFormField, options?: {
+    static registerFieldType(ft: 'Sig' | 'Btn' | 'Tx' | 'Ch', ctor: new (other?: PdfIndirectObject) => PdfFormField, options?: {
         fallback?: boolean;
     }): void;
-    static create(options: {
-        other: PdfIndirectObject;
-        form: FormContext<PdfFormField>;
-        parent?: PdfFormField;
-    }): PdfFormField;
 }
 /** Backward compatible alias */
 export { PdfFormField as PdfAcroFormField };

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

@@ -0,0 +1,519 @@
+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 { PdfObjectReference } from '../../core/objects/pdf-object-reference.js';
+import { PdfIndirectObject } from '../../core/objects/pdf-indirect-object.js';
+import { PdfName } from '../../core/objects/pdf-name.js';
+import { PdfNumber } from '../../core/objects/pdf-number.js';
+import { PdfFont } from '../../fonts/pdf-font.js';
+import { PdfStream } from '../../core/objects/pdf-stream.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 {
+    defaultGenerateAppearance = true;
+    /** @internal */
+    _form;
+    constructor(other) {
+        super();
+        if (other && !(other instanceof PdfIndirectObject)) {
+            this._form = other.form;
+        }
+    }
+    set form(f) {
+        this._form = f;
+    }
+    static create(other) {
+        if (!(other?.content instanceof PdfDictionary))
+            throw new Error('Invalid form field object');
+        const ft = other?.content.get('FT')?.as(PdfName)?.value;
+        const cls = ft ? PdfFormField._registry.get(ft) : undefined;
+        if (!cls) {
+            if (PdfFormField._fallbackCtor) {
+                return other.becomes(PdfFormField._fallbackCtor);
+            }
+            throw new Error(`Unsupported form field type: ${ft ?? 'unknown'}`);
+        }
+        return other.becomes(cls);
+    }
+    get parent() {
+        const resolved = this.content.get('Parent')?.resolve();
+        if (!resolved || !(resolved.content instanceof PdfDictionary))
+            return undefined;
+        return PdfFormField.create(resolved);
+    }
+    set parent(field) {
+        if (!field) {
+            this.content.delete('Parent');
+            return;
+        }
+        this.content.set('Parent', field.reference);
+        if (field instanceof PdfFormField) {
+            field.children = [...field.children, this];
+        }
+    }
+    get children() {
+        const kids = this.content.get('Kids')?.items ?? [];
+        const result = [];
+        for (const ref of kids) {
+            const resolved = ref.resolve();
+            if (!resolved || !(resolved.content instanceof PdfDictionary))
+                continue;
+            result.push(PdfFormField.create(resolved));
+        }
+        return result;
+    }
+    set children(fields) {
+        if (fields.length === 0) {
+            this.content.delete('Kids');
+            return;
+        }
+        this.content.set('Kids', PdfArray.refs(fields));
+        for (const child of fields) {
+            child.content.set('Parent', this.reference);
+        }
+    }
+    get siblings() {
+        return this.parent?.children ?? [];
+    }
+    get font() {
+        const fontName = this.fontName;
+        if (!fontName)
+            return null;
+        // Try resolving from default resources (DR) dict
+        const dr = this.defaultResources;
+        const fontDict = dr?.get('Font');
+        if (fontDict instanceof PdfDictionary) {
+            const fontEntry = fontDict.get(fontName);
+            if (fontEntry instanceof PdfObjectReference) {
+                const resolved = fontEntry.resolve();
+                if (resolved?.content instanceof PdfDictionary) {
+                    const font = resolved.becomes(PdfFont);
+                    font.resourceName = fontName;
+                    return font;
+                }
+            }
+        }
+        // Fallback: standard font lookup (Helv, Helvetica, ZaDb, etc.)
+        return PdfFont.getStandardFont(fontName) ?? null;
+    }
+    get defaultResources() {
+        const dr = this.content.get('DR');
+        const drDict = dr instanceof PdfObjectReference ? dr.resolve()?.content : dr;
+        return ((drDict instanceof PdfDictionary ? drDict : null) ??
+            this.parent?.defaultResources ??
+            this._form?.defaultResources ??
+            null);
+    }
+    set defaultResources(resources) {
+        if (resources === null) {
+            this.content.delete('DR');
+        }
+        else {
+            this.content.set('DR', resources);
+        }
+    }
+    /**
+     * Builds a Resources dictionary containing the font entry for `fontName`,
+     * resolved from DR (handling indirect references) or from a loaded font.
+     * Returns undefined if neither source provides the font.
+     */
+    buildFontResources(fontName) {
+        const dr = this.defaultResources;
+        const fontRaw = dr?.get('Font');
+        let drFontDict;
+        if (fontRaw instanceof PdfObjectReference) {
+            const resolved = fontRaw.resolve()?.content;
+            if (resolved instanceof PdfDictionary)
+                drFontDict = resolved;
+        }
+        else if (fontRaw instanceof PdfDictionary) {
+            drFontDict = fontRaw;
+        }
+        if (drFontDict && drFontDict.get(fontName)) {
+            const resFontDict = new PdfDictionary();
+            resFontDict.set(fontName, drFontDict.get(fontName));
+            const resources = new PdfDictionary();
+            resources.set('Font', resFontDict);
+            return resources;
+        }
+        const font = this.font;
+        if (font && !PdfFont.getStandardFont(fontName)) {
+            const fontDict = new PdfDictionary();
+            fontDict.set(fontName, font.reference);
+            const resources = new PdfDictionary();
+            resources.set('Font', fontDict);
+            return resources;
+        }
+        return undefined;
+    }
+    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;
+            const encodingMap = this.font?.encodingMap ??
+                (this.fontName
+                    ? this._form?.fontEncodingMaps?.get(this.fontName)
+                    : undefined);
+            if (encodingMap) {
+                return decodeWithFontEncoding(v.raw, 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.generateAppearance();
+            for (const sibling of this.siblings) {
+                if (sibling !== this &&
+                    sibling.rect &&
+                    sibling.defaultGenerateAppearance) {
+                    sibling.generateAppearance();
+                }
+            }
+            // Separated field/widget structure: field has no Rect but its Kids
+            // are widget annotations that do. Generate appearances for them.
+            if (!this.rect) {
+                for (const child of this.children) {
+                    if (child.rect && child.defaultGenerateAppearance) {
+                        if (this._form)
+                            child.form = this._form;
+                        child.generateAppearance();
+                    }
+                }
+            }
+        }
+        if (this._form) {
+            this._form.xfa?.datasets?.updateField(this.name, this.value);
+        }
+    }
+    /**
+     * 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;
+    }
+    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?.defaultAppearance ??
+            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 undefined;
+        return kidsArray;
+    }
+    set kids(kids) {
+        if (kids.length === 0) {
+            this.content.delete('Kids');
+            return;
+        }
+        const kidsArray = new PdfArray(kids);
+        this.content.set('Kids', kidsArray);
+    }
+    setAppearanceStream(stream) {
+        this.appearanceStreamDict ||= new PdfDictionary();
+        if (stream instanceof PdfIndirectObject) {
+            this.appearanceStreamDict.set('N', stream.reference);
+        }
+        else {
+            const dict = new PdfDictionary();
+            for (const key in stream) {
+                dict.set(key, stream[key].reference);
+            }
+            this.appearanceStreamDict.set('N', dict);
+        }
+    }
+    getAppearanceStream(setting) {
+        const n = this.appearanceStreamDict?.get('N');
+        if (!n)
+            return null;
+        if (n instanceof PdfObjectReference) {
+            const resolved = n.resolve();
+            if (resolved?.content instanceof PdfStream) {
+                return resolved;
+            }
+        }
+        else if (n instanceof PdfDictionary) {
+            const key = setting ??
+                this.content.get('AS')?.as(PdfName)?.value ??
+                undefined;
+            if (key) {
+                const entry = n.get(key);
+                if (entry instanceof PdfObjectReference) {
+                    const resolved = entry.resolve();
+                    if (resolved?.content instanceof PdfStream) {
+                        return resolved;
+                    }
+                }
+            }
+        }
+        return null;
+    }
+    static _fallbackCtor;
+    static _registry = new Map();
+    static registerFieldType(ft, ctor, options) {
+        PdfFormField._registry.set(ft, ctor);
+        if (options?.fallback) {
+            PdfFormField._fallbackCtor = ctor;
+        }
+    }
+}
+/** Backward compatible alias */
+export { PdfFormField as PdfAcroFormField };

package/dist/acroform/fields/{PdfSignatureFormField.d.ts → pdf-signature-form-field.d.ts}

@@ -1,4 +1,4 @@
-import { PdfFormField } from './PdfFormField.js';
+import { PdfFormField } from './pdf-form-field.js';
 /**
  * Signature form field subtype.
  */

package/dist/acroform/fields/{PdfSignatureFormField.js → pdf-signature-form-field.js}

@@ -1,4 +1,4 @@
-import { PdfFormField } from './PdfFormField.js';
+import { PdfFormField } from './pdf-form-field.js';
 /**
  * Signature form field subtype.
  */

package/dist/acroform/fields/{PdfTextFormField.d.ts → pdf-text-form-field.d.ts}

@@ -1,4 +1,4 @@
-import { PdfFormField } from './PdfFormField.js';
+import { PdfFormField } from './pdf-form-field.js';
 /**
  * Text form field subtype.
  */