pdf-lite 1.2.1 → 1.3.1

package/EXAMPLES.md

@@ -1109,7 +1109,7 @@ console.log('Created form-empty.pdf with empty form fields')
 const emptyFormBytes = await fs.readFile(`${tmpFolder}/form-empty.pdf`)
 const filledDocument = await PdfDocument.fromBytes([emptyFormBytes])
 
-const acroform = await filledDocument.acroForm.getAcroForm()
+const acroform = await filledDocument.acroForm.read()
 if (!acroform) {
     throw new Error('No AcroForm found in the document')
 }

package/dist/acroform/acroform.d.ts

@@ -8,6 +8,7 @@ import { PdfName } from '../core/objects/pdf-name.js';
 import { PdfBoolean } from '../core/objects/pdf-boolean.js';
 import { PdfNumber } from '../core/objects/pdf-number.js';
 import { PdfFont } from '../fonts/pdf-font.js';
+import { PdfStream } from '../core/objects/pdf-stream.js';
 /**
  * Field types for AcroForm fields
  */
@@ -17,9 +18,31 @@ export declare const PdfFieldType: {
     readonly Choice: "Ch";
     readonly Signature: "Sig";
 };
-export type PdfFieldType = (typeof PdfFieldType)[keyof typeof PdfFieldType];
-export declare class PdfAcroFormField extends PdfDictionary<{
-    FT: PdfName<PdfFieldType>;
+export type PdfFieldType = keyof typeof PdfFieldType;
+export type PdfAppearanceStreamDictionary = PdfDictionary<{
+    /** Appearance streams for different states */
+    N: PdfObjectReference | PdfDictionary;
+    R?: PdfObjectReference | PdfDictionary;
+    D?: PdfObjectReference | PdfDictionary;
+}>;
+export type PdfDefaultResourcesDictionary = PdfDictionary<{
+    /** Font resources used in the form */
+    Font?: PdfDictionary;
+    /** Procedure sets */
+    ProcSet?: PdfArray;
+    /** Extended graphics states */
+    ExtGState?: PdfDictionary;
+    /** Color spaces */
+    ColorSpace?: PdfDictionary;
+    /** Patterns */
+    Pattern?: PdfDictionary;
+    /** Shading dictionaries */
+    Shading?: PdfDictionary;
+    /** External objects */
+    XObject?: PdfDictionary;
+}>;
+export declare class PdfAcroFormField extends PdfIndirectObject<PdfDictionary<{
+    FT: PdfName<(typeof PdfFieldType)[keyof typeof PdfFieldType]>;
     T?: PdfString;
     V?: PdfString | PdfName;
     DV?: PdfString | PdfName;
@@ -34,12 +57,25 @@ export declare class PdfAcroFormField extends PdfDictionary<{
     MK?: PdfDictionary;
     Type?: PdfName<'Annot'>;
     Subtype?: PdfName<'Widget'>;
-}> {
+    AP?: PdfAppearanceStreamDictionary;
+    Q?: PdfNumber;
+    MaxLen?: PdfNumber;
+    Opt?: PdfArray<PdfString>;
+}>> {
     parent?: PdfAcroFormField;
-    readonly container?: PdfIndirectObject;
+    defaultGenerateAppearance: boolean;
+    private _appearanceStream?;
+    private _appearanceStreamYes?;
+    private form?;
     constructor(options?: {
-        container?: PdfIndirectObject;
+        other?: PdfIndirectObject;
+        form?: PdfAcroForm;
     });
+    get encodingMap(): Map<number, string> | undefined;
+    /**
+     * Convenience method to check if field dictionary is modified
+     */
+    isModified(): boolean;
     /**
      * Gets the field type
      */
@@ -68,7 +104,7 @@ export declare class PdfAcroFormField extends PdfDictionary<{
      */
     set defaultValue(val: string);
     get value(): string;
-    set value(val: string);
+    set value(val: string | PdfString);
     get checked(): boolean;
     set checked(isChecked: boolean);
     get fontSize(): number | null;
@@ -89,11 +125,19 @@ export declare class PdfAcroFormField extends PdfDictionary<{
      */
     set flags(flags: number);
     /**
-     * Checks if the field is read-only
+     * Gets annotation flags (for visual appearance and behavior)
+     */
+    get annotationFlags(): number;
+    /**
+     * Sets annotation flags
+     */
+    set annotationFlags(flags: number);
+    /**
+     * Checks if the field is read-only (Ff bit 1)
      */
     get readOnly(): boolean;
     /**
-     * Sets the field as read-only or editable
+     * Sets the field as read-only or editable (Ff bit 1)
      */
     set readOnly(isReadOnly: boolean);
     /**
@@ -120,23 +164,216 @@ export declare class PdfAcroFormField extends PdfDictionary<{
      * Sets the field as a password field (for text fields)
      */
     set password(isPassword: boolean);
+    /**
+     * Checks if the field is a comb field (characters distributed evenly across cells)
+     */
+    get comb(): boolean;
+    /**
+     * Gets the quadding (text alignment) for this field.
+     * 0 = left-justified, 1 = centered, 2 = right-justified
+     */
+    get quadding(): number;
+    /**
+     * Sets the quadding (text alignment) for this field.
+     * 0 = left-justified, 1 = centered, 2 = right-justified
+     */
+    set quadding(q: number);
+    /**
+     * Gets the options for choice fields (dropdowns, list boxes).
+     * Returns an array of option strings.
+     */
+    get options(): string[];
+    /**
+     * Sets the options for choice fields (dropdowns, list boxes).
+     * Pass an array of strings.
+     */
+    set options(options: string[]);
+    get defaultAppearance(): string | null;
+    set defaultAppearance(da: string);
+    set combo(isCombo: boolean);
+    get combo(): boolean;
+    get radio(): boolean;
+    set radio(isRadio: boolean);
+    get noToggleToOff(): boolean;
+    set noToggleToOff(noToggle: boolean);
+    get combField(): boolean;
+    set combField(isComb: boolean);
+    get maxLen(): number | null;
+    set maxLen(maxLen: number | null);
+    /**
+     * If true, the annotation is invisible (F bit 1)
+     */
+    get invisible(): boolean;
+    set invisible(value: boolean);
+    /**
+     * If true, the annotation is hidden (F bit 2)
+     */
+    get hidden(): boolean;
+    set hidden(value: boolean);
+    /**
+     * If true, print the annotation when printing (F bit 3)
+     */
+    get print(): boolean;
+    set print(value: boolean);
+    /**
+     * If true, do not zoom annotation when zooming (F bit 4)
+     */
+    get noZoom(): boolean;
+    set noZoom(value: boolean);
+    /**
+     * If true, do not rotate annotation when rotating (F bit 5)
+     */
+    get noRotate(): boolean;
+    set noRotate(value: boolean);
+    /**
+     * If true, do not display annotation on screen (F bit 6)
+     */
+    get noView(): boolean;
+    set noView(value: boolean);
+    /**
+     * If true, annotation is locked (F bit 8)
+     */
+    get locked(): boolean;
+    set locked(value: boolean);
+    /**
+     * If true, field value should not be exported (Ff bit 3)
+     */
+    get noExport(): boolean;
+    set noExport(value: boolean);
+    /**
+     * If true, field is a pushbutton (Ff bit 17)
+     */
+    get pushButton(): boolean;
+    set pushButton(value: boolean);
+    /**
+     * If true, text field allows editing (Ff bit 19)
+     */
+    get edit(): boolean;
+    set edit(value: boolean);
+    /**
+     * If true, choice options should be sorted alphabetically (Ff bit 20)
+     */
+    get sort(): boolean;
+    set sort(value: boolean);
+    /**
+     * If true, allows multiple selections in choice field (Ff bit 22)
+     */
+    get multiSelect(): boolean;
+    set multiSelect(value: boolean);
+    /**
+     * If true, do not spell check this field (Ff bit 23)
+     */
+    get doNotSpellCheck(): boolean;
+    set doNotSpellCheck(value: boolean);
+    /**
+     * If true, do not scroll text field (Ff bit 24)
+     */
+    get doNotScroll(): boolean;
+    set doNotScroll(value: boolean);
+    /**
+     * If true, commit field value immediately on selection change (Ff bit 27)
+     */
+    get commitOnSelChange(): boolean;
+    set commitOnSelChange(value: boolean);
+    get kids(): PdfObjectReference[];
+    set kids(kids: PdfObjectReference[]);
+    get appearanceStreamDict(): PdfAppearanceStreamDictionary | null;
+    set appearanceStreamDict(dict: PdfAppearanceStreamDictionary | null);
+    /**
+     * Generates an appearance stream for a text field using iText's approach.
+     *
+     * This generates an appearance with text using the same positioning formula as iText:
+     * - textY = (height - fontSize) / 2 + fontSize * 0.2
+     * - Wrapped in marked content blocks (/Tx BMC ... EMC)
+     * - Field remains editable unless makeReadOnly is set
+     *
+     * For editable fields (default, no options):
+     * - Text visible immediately
+     * - Field remains fully editable
+     * - No save dialog (needAppearances = false)
+     * - Text positioning matches iText
+     *
+     * For read-only fields (makeReadOnly: true):
+     * - Same appearance generation
+     * - Field is set as read-only
+     *
+     * @param options.makeReadOnly - If true, sets field as read-only
+     * @returns true if appearance was generated successfully
+     */
+    generateAppearance(options?: {
+        makeReadOnly?: boolean;
+        textYOffset?: number;
+    }): boolean;
+    /**
+     * Generates appearance for text fields
+     * @internal
+     */
+    private generateTextAppearance;
+    /**
+     * Generates appearance for button fields (checkboxes, radio buttons)
+     * @internal
+     */
+    private generateButtonAppearance;
+    /**
+     * Generates appearance for choice fields (dropdowns, list boxes)
+     * @internal
+     */
+    private generateChoiceAppearance;
+    /**
+     * Gets the stored appearance stream if one has been generated.
+     * For button fields, returns the appropriate stream based on the current state.
+     * @internal
+     */
+    getAppearanceStream(): PdfStream | undefined;
+    /**
+     * Gets all appearance streams for writing to PDF.
+     * For button fields, returns both Off and Yes states.
+     * For other fields, returns just the primary appearance.
+     * @internal
+     */
+    getAppearanceStreamsForWriting(): {
+        primary: PdfStream;
+        secondary?: PdfStream;
+    } | undefined;
+    /**
+     * Sets the appearance dictionary reference for this field.
+     * @internal - This is called automatically by PdfAcroForm.write()
+     */
+    setAppearanceReference(appearanceStreamRef: PdfObjectReference, appearanceStreamYesRef?: PdfObjectReference): void;
 }
-export declare class PdfAcroForm<T extends Record<string, string> = Record<string, string>> extends PdfDictionary<{
+export declare class PdfAcroForm<T extends Record<string, string> = Record<string, string>> extends PdfIndirectObject<PdfDictionary<{
     Fields: PdfArray<PdfObjectReference>;
     NeedAppearances?: PdfBoolean;
     SigFlags?: PdfNumber;
     CO?: PdfArray<PdfObjectReference>;
-    DR?: PdfDictionary;
+    DR?: PdfDefaultResourcesDictionary;
     DA?: PdfString;
     Q?: PdfNumber;
-}> {
+}>> {
     fields: PdfAcroFormField[];
-    readonly container?: PdfIndirectObject;
-    constructor(options: {
-        dict: PdfDictionary;
+    readonly fontEncodingMaps: Map<string, Map<number, string>>;
+    private document?;
+    constructor(options?: {
+        other?: PdfIndirectObject;
         fields?: PdfAcroFormField[];
-        container?: PdfIndirectObject;
+        document?: PdfDocument;
     });
+    /**
+     * Convenience method to get a value from the form dictionary
+     */
+    get(key: string): any;
+    /**
+     * Convenience method to set a value in the form dictionary
+     */
+    set(key: string, value: any): void;
+    /**
+     * Convenience method to delete a key from the form dictionary
+     */
+    delete(key: string): void;
+    /**
+     * Convenience method to check if form dictionary is modified
+     */
+    isModified(): boolean;
     /**
      * Gets the NeedAppearances flag
      */
@@ -170,6 +407,14 @@ export declare class PdfAcroForm<T extends Record<string, string> = Record<strin
      * Sets the default quadding (alignment) for the form
      */
     set defaultQuadding(q: number);
+    /**
+     * Gets the default resources dictionary for the form
+     */
+    get defaultResources(): PdfDefaultResourcesDictionary | null;
+    /**
+     * Sets the default resources dictionary for the form
+     */
+    set defaultResources(resources: PdfDefaultResourcesDictionary | null);
     /**
      * Sets multiple field values by field name.
      * @param values Object with field names as keys and values to set
@@ -177,7 +422,18 @@ export declare class PdfAcroForm<T extends Record<string, string> = Record<strin
     setValues(values: Partial<T>): void;
     importData(fields: T): void;
     exportData(): Partial<T>;
+    /**
+     * Gets the encoding map for a specific font in the form's resources.
+     * Returns null if no custom encoding is found.
+     * Results are cached for performance.
+     */
+    getFontEncodingMap(fontName: string): Promise<Map<number, string> | null>;
     static fromDocument(document: PdfDocument): Promise<PdfAcroForm | null>;
+    /**
+     * Pre-caches encoding maps for all fonts used in the form fields.
+     * This makes subsequent field value access faster and synchronous.
+     */
+    private cacheAllFontEncodings;
     /**
      * Gets or creates the Annots array for a page.
      * Returns the array and metadata about whether it's an indirect object.