pdf-lite 1.6.1 → 1.6.2

package/README.md

@@ -92,6 +92,89 @@ await document.encrypt()
 console.log(document.toString())
 ```
 
+### Filling AcroForms
+
+```typescript
+import { PdfDocument } from 'pdf-lite/pdf/pdf-document'
+import { readFile, writeFile } from 'fs/promises'
+
+const pdfBytes = await readFile('form.pdf')
+const doc = await PdfDocument.fromBytes([pdfBytes])
+
+const form = doc.acroform
+if (!form) throw new Error('No AcroForm found')
+
+// Set multiple field values at once
+form.setValues({
+    name: 'John Doe',
+    email: 'john@example.com',
+    subscribe: 'Yes', // checkbox: 'Yes' or 'Off'
+})
+
+// Or work with individual fields
+const field = form.fields.find((f) => f.name === 'name')
+field.value = 'Jane Doe'
+
+// Export all current values
+const values = form.exportData()
+// => { name: 'Jane Doe', email: 'john@example.com', subscribe: 'Yes' }
+
+await writeFile('filled.pdf', doc.toBytes())
+```
+
+### Generating Appearances
+
+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
+// Auto-generate appearances when setting values (default behavior)
+field.value = 'Hello' // appearance is generated automatically
+
+// Or generate manually with options
+field.generateAppearance({ makeReadOnly: true })
+
+// Configure font and size for a field
+field.fontSize = 14
+field.fontName = 'Helv'
+
+// For checkbox fields
+const checkbox = form.fields.find((f) => f.name === 'agree')
+checkbox.checked = true
+checkbox.generateAppearance()
+
+// For choice fields (dropdowns/listboxes)
+const dropdown = form.fields.find((f) => f.name === 'country')
+dropdown.value = 'US'
+dropdown.generateAppearance()
+```
+
+### Working with Fonts
+
+```typescript
+import { PdfFont } from 'pdf-lite'
+
+// Standard PDF fonts (built into all PDF readers)
+const helvetica = PdfFont.fromStandardFont('Helvetica')
+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)
+
+// Use pre-defined font constants
+const font = PdfFont.HELVETICA_BOLD
+
+// Assign resource names for use in content streams
+customFont.resourceName = 'F1'
+
+// Add to document
+document.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
+
 ### Signing PDFs
 
 ```typescript
@@ -187,14 +270,47 @@ Long-Term Validation (LTV) support ensures that digital signatures remain valid
 - [x] Timestamping
 - [x] Verification of existing signatures
 
-### AcroForm filling
+### AcroForms
+
+Supports reading, filling, and creating AcroForm fields within PDF documents.
 
-Supports filling out AcroForm forms within PDF documents, allowing for dynamic content generation and user interaction.
+**Field types:**
 
-- [x] Text fields
+- [x] Text fields (single-line, multi-line, comb, password)
 - [x] Checkboxes
 - [x] Radio buttons
-- [x] Dropdowns
+- [x] Dropdowns (combo boxes)
+- [x] List boxes
+- [x] Signature fields
+
+**Form operations:**
+
+- [x] Import/export field values (`importData`, `exportData`, `setValues`)
+- [x] Read individual field properties (name, value, type, flags)
+- [x] Hierarchical field support (parent/child/sibling fields)
+
+### Appearance Streams
+
+Automatic generation of visual appearance streams for form fields, so filled forms render correctly in all PDF viewers without relying on `NeedAppearances`.
+
+- [x] Text field rendering (word wrap, auto-sizing, comb layout)
+- [x] Checkbox/radio button rendering
+- [x] Dropdown/list box rendering
+- [x] Font resolution from field, form, or document resources
+- [x] Auto-size font (fontSize=0) for single-line text fields
+- [x] Custom font color via Default Appearance strings
+
+### Fonts
+
+Supports standard PDF fonts and embedding custom fonts.
+
+- [x] All 14 standard PDF fonts (Helvetica, Times, Courier, Symbol, ZapfDingbats + variants)
+- [x] TrueType font embedding (TTF)
+- [x] OpenType font embedding (OTF, non-CFF)
+- [x] WOFF font embedding
+- [x] Auto-detect font format via `PdfFont.fromBytes()`
+- [x] Font encoding maps (WinAnsi, Unicode/Identity-H)
+- [x] Character width metrics
 
 ### XFA Forms
 

package/dist/acroform/appearance/pdf-graphics.js

@@ -192,13 +192,14 @@ export class PdfGraphics {
         const startSize = this.currentFont.size;
         const minSize = 0.5;
         const fits = (size) => {
-            if (this.measureTextWidth(text, size) > maxWidth)
-                return false;
             if (maxHeight !== undefined) {
+                // Wrapping mode: text is allowed to span multiple lines,
+                // so only check that the wrapped result fits the box.
                 const lines = this.wrapTextToLines(text, maxWidth, size);
                 return lines.length * size * lineHeight <= maxHeight;
             }
-            return true;
+            // Single-line mode: text must fit within maxWidth.
+            return this.measureTextWidth(text, size) <= maxWidth;
         };
         if (fits(startSize))
             return startSize;

package/dist/acroform/appearance/pdf-text-appearance-stream.js

@@ -1,6 +1,7 @@
 import { PdfDefaultAppearance } from '../fields/pdf-default-appearance.js';
 import { PdfAppearanceStream } from './pdf-appearance-stream.js';
 import { PdfGraphics } from './pdf-graphics.js';
+const DEFAULT_FONT_SIZE = 12;
 /**
  * Appearance stream for text fields (single-line, multiline, comb).
  * Enhanced with word wrapping and automatic font scaling.
@@ -16,29 +17,44 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
         const padding = 2;
         const availableWidth = width - 2 * padding;
         const availableHeight = height - 2 * padding;
+        const autoSize = ctx.da.fontSize <= 0;
         // Create graphics with font context for text measurement
         const g = new PdfGraphics({
             resolvedFonts: ctx.resolvedFonts,
         });
         g.beginMarkedContent();
         g.save();
-        // Set initial font to enable measurement
-        g.setDefaultAppearance(ctx.da);
-        let finalFontSize = ctx.da.fontSize;
-        let lines = [];
-        if (ctx.multiline) {
+        // Bootstrap with a reference size so measureTextWidth works
+        g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, DEFAULT_FONT_SIZE, ctx.da.colorOp));
+        // ── Determine font size ──────────────────────────────────────
+        let finalFontSize;
+        if (autoSize) {
+            // Acrobat auto-size: default to 12pt with wrapping, then
+            // shrink only if the wrapped text still doesn't fit.
+            finalFontSize = DEFAULT_FONT_SIZE;
             const testLines = g.wrapTextToLines(value, availableWidth);
-            const lineHeight = finalFontSize * 1.2;
-            if (testLines.length * lineHeight > availableHeight) {
-                // Scale font down to fit
+            if (testLines.length * DEFAULT_FONT_SIZE * 1.2 > availableHeight) {
                 finalFontSize = g.calculateFittingFontSize(value, availableWidth, availableHeight, 1.2);
-                const adjustedDA = new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp);
-                g.setDefaultAppearance(adjustedDA);
-                lines = g.wrapTextToLines(value, availableWidth);
             }
-            else {
-                lines = testLines;
+            finalFontSize = Math.max(finalFontSize, 0.5);
+        }
+        else {
+            finalFontSize = ctx.da.fontSize;
+        }
+        // ── Render ───────────────────────────────────────────────────
+        const finalDA = new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp);
+        g.setDefaultAppearance(finalDA);
+        let lines = [];
+        if (ctx.multiline || autoSize) {
+            if (!autoSize) {
+                const testLines = g.wrapTextToLines(value, availableWidth);
+                const lineHeight = finalFontSize * 1.2;
+                if (testLines.length * lineHeight > availableHeight) {
+                    finalFontSize = g.calculateFittingFontSize(value, availableWidth, availableHeight, 1.2);
+                    g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp));
+                }
             }
+            lines = g.wrapTextToLines(value, availableWidth);
             const renderLineHeight = finalFontSize * 1.2;
             const startY = height - padding - finalFontSize;
             g.beginText();
@@ -53,7 +69,6 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
         else if (ctx.comb && ctx.maxLen) {
             const cellWidth = width / ctx.maxLen;
             const chars = [...value];
-            // Calculate font size to fit the widest character in its cell
             let maxCharWidth = 0;
             let widestChar = chars[0] ?? '';
             for (const char of chars) {
@@ -65,8 +80,7 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
             }
             if (maxCharWidth > cellWidth) {
                 finalFontSize = g.calculateFittingFontSize(widestChar, cellWidth);
-                const adjustedDA = new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp);
-                g.setDefaultAppearance(adjustedDA);
+                g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp));
             }
             const textY = (height - finalFontSize) / 2 + finalFontSize * 0.2;
             g.beginText();
@@ -79,12 +93,13 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
             g.endText();
         }
         else {
-            // Single line text
-            const textWidth = g.measureTextWidth(value);
-            if (textWidth > availableWidth) {
-                finalFontSize = g.calculateFittingFontSize(value, availableWidth);
-                const adjustedDA = new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp);
-                g.setDefaultAppearance(adjustedDA);
+            // Single line — for non-auto-size, shrink if text overflows
+            if (!autoSize) {
+                const textWidth = g.measureTextWidth(value);
+                if (textWidth > availableWidth) {
+                    finalFontSize = g.calculateFittingFontSize(value, availableWidth);
+                    g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp));
+                }
             }
             const textY = (height - finalFontSize) / 2 + finalFontSize * 0.2;
             g.beginText();

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

@@ -20,20 +20,35 @@ export class PdfButtonFormField extends PdfFormField {
             this.content.delete('AS');
             return false;
         }
-        this.content.set('V', new PdfName(strVal));
-        fieldParent?.content.set('V', new PdfName(strVal));
-        this.content.set('AS', new PdfName(strVal));
+        // Check if the value matches an existing appearance state;
+        // otherwise map truthy values to the widget's "on" state (the
+        // first state that isn't "Off"), falling back to "Yes".
+        const states = this.appearanceStates;
+        let resolved;
+        if (states.includes(strVal)) {
+            resolved = strVal;
+        }
+        else if (strVal === 'Off' || strVal === 'No') {
+            resolved = 'Off';
+        }
+        else {
+            resolved = states.find((s) => s !== 'Off') ?? 'Yes';
+        }
+        this.content.set('V', new PdfName(resolved));
+        fieldParent?.content.set('V', new PdfName(resolved));
+        this.content.set('AS', new PdfName(resolved));
         return true;
     }
     get checked() {
         const v = this.content.get('V') ?? this.parent?.content.get('V');
-        return v instanceof PdfName && v.value === 'Yes';
+        return v instanceof PdfName && v.value !== 'Off';
     }
     set checked(isChecked) {
         const target = this.parent ?? this;
         if (isChecked) {
-            target.content.set('V', new PdfName('Yes'));
-            this.content.set('AS', new PdfName('Yes'));
+            const onState = this.appearanceStates.find((s) => s !== 'Off') ?? 'Yes';
+            target.content.set('V', new PdfName(onState));
+            this.content.set('AS', new PdfName(onState));
         }
         else {
             target.content.set('V', new PdfName('Off'));
@@ -56,8 +71,9 @@ export class PdfButtonFormField extends PdfFormField {
             height,
             contentStream: '',
         });
+        const onState = this.appearanceStates.find((s) => s !== 'Off') ?? 'Yes';
         this.setAppearanceStream({
-            Yes: yesAppearance,
+            [onState]: yesAppearance,
             Off: noAppearance,
         });
         if (options?.makeReadOnly) {

package/dist/acroform/fields/pdf-default-appearance.js

@@ -50,10 +50,7 @@ export class PdfDefaultAppearance extends PdfString {
         if (!fontMatch)
             return null;
         const fontName = fontMatch[1];
-        let fontSize = parseFloat(fontMatch[2]);
-        if (!fontSize || fontSize <= 0) {
-            fontSize = 12;
-        }
+        const fontSize = parseFloat(fontMatch[2]) || 0;
         let colorOp = '0 g';
         const rgMatch = da.match(/([\d.]+\s+[\d.]+\s+[\d.]+)\s+rg/);
         const gMatch = da.match(/([\d.]+)\s+g/);

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

@@ -107,6 +107,11 @@ export declare abstract class PdfFormField extends PdfWidgetAnnotation {
     setAppearanceStream(stream: PdfIndirectObject | {
         [key: string]: PdfIndirectObject;
     }): void;
+    /**
+     * Returns the list of appearance state names from the normal appearance
+     * dictionary (e.g. ["Yes", "Off"] for a checkbox).
+     */
+    get appearanceStates(): string[];
     getAppearanceStream(setting?: string): PdfIndirectObject<PdfStream> | null;
     private static _fallbackCtor?;
     private static _registry;

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

@@ -480,6 +480,17 @@ export class PdfFormField extends PdfWidgetAnnotation {
             this.appearanceStreamDict.set('N', dict);
         }
     }
+    /**
+     * Returns the list of appearance state names from the normal appearance
+     * dictionary (e.g. ["Yes", "Off"] for a checkbox).
+     */
+    get appearanceStates() {
+        const n = this.appearanceStreamDict?.get('N');
+        if (n instanceof PdfDictionary) {
+            return Array.from(n.entries(), ([key]) => key);
+        }
+        return [];
+    }
     getAppearanceStream(setting) {
         const n = this.appearanceStreamDict?.get('N');
         if (!n)

package/package.json

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