pdf-lite 1.4.0 → 1.6.0

package/EXAMPLES.md

@@ -10,38 +10,11 @@ import { PdfArray } from 'pdf-lite/core/objects/pdf-array'
 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 { PdfDocument } from 'pdf-lite/pdf/pdf-document'
-
-function createPage(
-    contentStreamRef: PdfObjectReference,
-): PdfIndirectObject<PdfDictionary> {
-    const pageDict = new PdfDictionary()
-    pageDict.set('Type', new PdfName('Page'))
-    pageDict.set(
-        'MediaBox',
-        new PdfArray([
-            new PdfNumber(0),
-            new PdfNumber(0),
-            new PdfNumber(612),
-            new PdfNumber(792),
-        ]),
-    )
-    pageDict.set('Contents', contentStreamRef)
-    return new PdfIndirectObject({ content: pageDict })
-}
-
-function createPages(
-    pages: PdfIndirectObject<PdfDictionary>[],
-): PdfIndirectObject<PdfDictionary> {
-    const pagesDict = new PdfDictionary()
-    pagesDict.set('Type', new PdfName('Pages'))
-    pagesDict.set('Kids', new PdfArray(pages.map((x) => x.reference)))
-    pagesDict.set('Count', new PdfNumber(pages.length))
-    return new PdfIndirectObject({ content: pagesDict })
-}
+import { PdfPage } from 'pdf-lite/pdf/pdf-page'
+import { PdfPages } from 'pdf-lite/pdf/pdf-pages'
 
 function createCatalog(
     pagesRef: PdfObjectReference,
@@ -89,16 +62,18 @@ const contentStream = new PdfIndirectObject({
     }),
 })
 
-// Create a page
-const page = createPage(contentStream.reference)
-// Add resources to the page
-page.content.set('Resources', resources.reference)
+// Create a page using PdfPage
+const page = new PdfPage()
+page.mediaBox = [0, 0, 612, 792]
+page.contents = contentStream.reference
+page.resources = resources.reference
 document.add(page)
 
-// Create pages collection
-const pages = createPages([page])
-// Set parent reference for the page
-page.content.set('Parent', pages.reference)
+// Create pages collection using PdfPages
+const pages = new PdfPages()
+pages.kids = new PdfArray([page.reference])
+pages.count = 1
+page.parent = pages
 document.add(pages)
 
 // Create catalog
@@ -109,7 +84,7 @@ document.add(catalog)
 document.trailerDict.set('Root', catalog.reference)
 
 document.add(contentStream)
-await document.commit()
+await document.finalize()
 
 const file = `${import.meta.dirname}/tmp/created.pdf`
 console.log(`Writing PDF to: ${file}`)
@@ -225,7 +200,7 @@ document.add(catalog)
 document.trailerDict.set('Root', catalog.reference)
 
 document.add(contentStream)
-await document.commit()
+await document.finalize()
 
 document.securityHandler = new PdfV2SecurityHandler({
     password: 'up',
@@ -577,14 +552,7 @@ document.add(catalog)
 // Set the catalog as the root
 document.trailerDict.set('Root', catalog.reference)
 
-// IMPORTANT: Add all signatures LAST - after all other objects
-// This ensures the ByteRange is calculated correctly for each signature
-allSignatures.forEach((sig) => {
-    document.startNewRevision()
-    document.add(sig)
-})
-
-await document.commit()
+await document.finalize()
 
 const tmpFolder = `${import.meta.dirname}/tmp`
 await fs.mkdir(tmpFolder, { recursive: true })
@@ -694,7 +662,7 @@ document.add(catalog)
 document.trailerDict.set('Root', catalog.reference)
 document.add(contentStream)
 
-await document.commit()
+await document.finalize()
 // Save the original PDF
 const originalPdfPath = `${tmpFolder}/original.pdf`
 await fs.writeFile(originalPdfPath, document.toBytes())
@@ -706,7 +674,9 @@ console.log('\nStep 2: Loading PDF and performing incremental update...')
 
 // Read the existing PDF
 const existingPdfBytes = await fs.readFile(originalPdfPath)
-const loadedDocument = await PdfDocument.fromBytes([existingPdfBytes])
+const loadedDocument = await PdfDocument.fromBytes([existingPdfBytes], {
+    incremental: true,
+})
 
 // Lock existing revisions to enable incremental mode
 // This ensures changes are added as new revisions instead of modifying existing ones
@@ -726,7 +696,7 @@ const newContentStream = new PdfIndirectObject({
 
 // Add the new content to the document
 loadedDocument.add(newContentStream)
-await loadedDocument.commit()
+await loadedDocument.finalize()
 
 // Save the incrementally updated PDF
 const updatedPdfPath = `${tmpFolder}/incremental-update.pdf`
@@ -768,7 +738,9 @@ console.log(`Original content preserved: ${originalBytesMatch ? 'Yes' : 'No'}`)
 // Step 4: Add another incremental revision
 console.log('\nStep 4: Adding another incremental revision...')
 
-const secondUpdate = await PdfDocument.fromBytes([updatedPdfBytes])
+const secondUpdate = await PdfDocument.fromBytes([updatedPdfBytes], {
+    incremental: true,
+})
 secondUpdate.setIncremental(true)
 
 const thirdRevisionContent = new PdfIndirectObject({
@@ -780,7 +752,7 @@ const thirdRevisionContent = new PdfIndirectObject({
 })
 
 secondUpdate.add(thirdRevisionContent)
-await secondUpdate.commit()
+await secondUpdate.finalize()
 
 const multiRevisionPdfPath = `${tmpFolder}/multi-revision.pdf`
 await fs.writeFile(multiRevisionPdfPath, secondUpdate.toBytes())
@@ -1092,7 +1064,7 @@ document.add(catalog)
 // Set the catalog as the root
 document.trailerDict.set('Root', catalog.reference)
 
-await document.commit()
+await document.finalize()
 
 // Save the empty form
 // This demonstrates creating a blank form that users can fill in
@@ -1109,7 +1081,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.read()
+const acroform = filledDocument.acroform
 if (!acroform) {
     throw new Error('No AcroForm found in the document')
 }
@@ -1119,7 +1091,6 @@ acroform.importData({
     phone: '+1 (555) 123-4567',
     subscribe: 'Off', // For checkbox, use the "Yes/Off" value
 })
-await filledDocument.acroForm.write(acroform)
 
 // Save the filled form
 await fs.writeFile(`${tmpFolder}/form-filled.pdf`, filledDocument.toBytes())
@@ -1808,7 +1779,7 @@ allSignatures.forEach((sig) => {
     document.add(sig)
 })
 
-await document.commit()
+await document.finalize()
 
 const documentBytes = document.toBytes()
 const newDocument = await PdfDocument.fromBytes([documentBytes])
@@ -1885,7 +1856,7 @@ async function main() {
 
     document.add(pages, catalog)
     document.trailerDict.set('Root', catalog.reference)
-    await document.commit()
+    await document.finalize()
 
     // Build content stream with different fonts
     // F1=Helvetica-Bold, F2=Times-Roman, F3=Courier, F4=Roboto
@@ -1930,11 +1901,13 @@ async function main() {
         }),
     })
 
-    // Embed fonts - FontManager will automatically add them to the /Pages Resources
-    const helveticaBold =
-        await document.fonts.embedStandardFont('Helvetica-Bold')
-    const timesRoman = await document.fonts.embedStandardFont('Times-Roman')
-    const courier = await document.fonts.embedStandardFont('Courier')
+    // Create standard fonts and assign resource names to match the content stream
+    const helveticaBold = PdfFont.fromStandardFont('Helvetica-Bold')
+    helveticaBold.resourceName = 'F1'
+    const timesRoman = PdfFont.fromStandardFont('Times-Roman')
+    timesRoman.resourceName = 'F2'
+    const courier = PdfFont.fromStandardFont('Courier')
+    courier.resourceName = 'F3'
 
     console.log(
         `Embedded standard fonts: ${helveticaBold}, ${timesRoman}, ${courier}`,
@@ -1960,6 +1933,7 @@ async function main() {
     // - Creates a ready-to-use PdfFont instance
     // - Throws descriptive errors for unsupported formats (WOFF2, CFF-based OTF)
     const robotoFont = PdfFont.fromBytes(fontData)
+    robotoFont.resourceName = 'F4'
 
     console.log(
         `Created PdfFont from bytes - Font name: ${robotoFont.fontName}`,
@@ -1969,15 +1943,22 @@ async function main() {
         `  Embedded font data preserved: ${robotoFont.fontData ? 'Yes' : 'No'}`,
     )
 
-    // Write the font to the document
-    // FontManager.write() automatically:
-    // - Assigns a resource name (F1, F2, F3, etc.)
-    // - Creates the container indirect object
-    // - Adds the font to the /Pages node Resources dictionary
-    // - All child pages inherit these fonts (even pages added later!)
-    await document.fonts.write(robotoFont)
+    // Add all fonts to the document
+    document.add(helveticaBold, timesRoman, courier, robotoFont)
     console.log(`Embedded custom font in PDF: ${robotoFont}`)
 
+    // Build a Font resource dictionary mapping resource names to font references
+    const fontDict = new PdfDictionary()
+    fontDict.set(helveticaBold.resourceName, helveticaBold.reference)
+    fontDict.set(timesRoman.resourceName, timesRoman.reference)
+    fontDict.set(courier.resourceName, courier.reference)
+    fontDict.set(robotoFont.resourceName, robotoFont.reference)
+
+    // Add font resources to the /Pages node so all child pages inherit them
+    const resourcesDict = new PdfDictionary()
+    resourcesDict.set('Font', fontDict)
+    pages.content.set('Resources', resourcesDict)
+
     console.log(`\nFont resource mappings:`)
     console.log(`  ${helveticaBold.resourceName} = Helvetica-Bold`)
     console.log(`  ${timesRoman.resourceName} = Times-Roman`)
@@ -1992,7 +1973,7 @@ async function main() {
     pages.content.set('Count', new PdfNumber(1))
 
     document.add(contentStream, page)
-    await document.commit()
+    await document.finalize()
 
     console.log(`\nFont resource mappings:`)
     console.log(`  ${helveticaBold.resourceName} = Helvetica-Bold`)

package/README.md

@@ -4,7 +4,7 @@
 
 A low-level, minimal-dependency, type-safe PDF library that works in the browser and Node.js.
 
-> **Note**: This library is actively developed and may not support all PDF features yet. However, it is designed to be extensible and can be improved over time.
+> **Note**: This library is actively developed and may not support all PDF features yet. However, it is designed to be extensible and can be improved over time. I would also not expect the API to be stable until at least version 2.0 as a lot of features are still being added and the API is evolving.
 
 PRs and issues are welcome!
 

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

@@ -1,4 +1,4 @@
-export { PdfAppearanceStream } from './PdfAppearanceStream.js';
-export { PdfTextAppearanceStream } from './PdfTextAppearanceStream.js';
-export { PdfButtonAppearanceStream } from './PdfButtonAppearanceStream.js';
-export { PdfChoiceAppearanceStream } from './PdfChoiceAppearanceStream.js';
+export { PdfAppearanceStream } from './pdf-appearance-stream.js';
+export { PdfTextAppearanceStream } from './pdf-text-appearance-stream.js';
+export { PdfButtonAppearanceStream } from './pdf-button-appearance-stream.js';
+export { PdfChoiceAppearanceStream } from './pdf-choice-appearance-stream.js';

package/dist/acroform/appearance/index.js

@@ -1,4 +1,4 @@
-export { PdfAppearanceStream } from './PdfAppearanceStream.js';
-export { PdfTextAppearanceStream } from './PdfTextAppearanceStream.js';
-export { PdfButtonAppearanceStream } from './PdfButtonAppearanceStream.js';
-export { PdfChoiceAppearanceStream } from './PdfChoiceAppearanceStream.js';
+export { PdfAppearanceStream } from './pdf-appearance-stream.js';
+export { PdfTextAppearanceStream } from './pdf-text-appearance-stream.js';
+export { PdfButtonAppearanceStream } from './pdf-button-appearance-stream.js';
+export { PdfChoiceAppearanceStream } from './pdf-choice-appearance-stream.js';

package/dist/acroform/appearance/{PdfAppearanceStream.d.ts → pdf-appearance-stream.d.ts}

@@ -1,15 +1,21 @@
 import { PdfDictionary } from '../../core/objects/pdf-dictionary.js';
 import { PdfStream } from '../../core/objects/pdf-stream.js';
 import { PdfIndirectObject } from '../../core/objects/pdf-indirect-object.js';
+import { PdfGraphics } from './pdf-graphics.js';
 /**
  * Base class for PDF appearance streams (Form XObjects).
  * Wraps a PdfStream as a PdfIndirectObject so it can be added directly to a document.
  */
 export declare class PdfAppearanceStream extends PdfIndirectObject<PdfStream> {
     constructor(options: {
-        width: number;
-        height: number;
-        contentStream: string;
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+        contentStream?: string;
         resources?: PdfDictionary;
     });
+    get contentStream(): string;
+    set contentStream(newContent: string);
+    set graphics(g: PdfGraphics);
 }

package/dist/acroform/appearance/{PdfAppearanceStream.js → pdf-appearance-stream.js}

@@ -15,18 +15,27 @@ export class PdfAppearanceStream extends PdfIndirectObject {
         appearanceDict.set('Subtype', new PdfName('Form'));
         appearanceDict.set('FormType', new PdfNumber(1));
         appearanceDict.set('BBox', new PdfArray([
-            new PdfNumber(0),
-            new PdfNumber(0),
-            new PdfNumber(options.width),
-            new PdfNumber(options.height),
+            new PdfNumber(options.x ?? 0),
+            new PdfNumber(options.y ?? 0),
+            new PdfNumber(options.width ?? 100),
+            new PdfNumber(options.height ?? 100),
         ]));
         if (options.resources) {
             appearanceDict.set('Resources', options.resources);
         }
         const stream = new PdfStream({
             header: appearanceDict,
-            original: options.contentStream,
+            original: options.contentStream ?? '',
         });
         super({ content: stream });
     }
+    get contentStream() {
+        return this.content.rawAsString;
+    }
+    set contentStream(newContent) {
+        this.content.rawAsString = newContent;
+    }
+    set graphics(g) {
+        this.contentStream = g.build();
+    }
 }

package/dist/acroform/appearance/{PdfButtonAppearanceStream.d.ts → pdf-button-appearance-stream.d.ts}

@@ -1,4 +1,5 @@
-import { PdfAppearanceStream } from './PdfAppearanceStream.js';
+import { PdfAppearanceStream } from './pdf-appearance-stream.js';
+import { PdfFormFieldFlags } from '../fields/pdf-form-field-flags.js';
 /**
  * Appearance stream for button fields (checkboxes, radio buttons).
  */
@@ -8,5 +9,5 @@ export declare class PdfButtonAppearanceStream extends PdfAppearanceStream {
         height: number;
         contentStream: string;
     });
-    static buildYesContent(width: number, height: number, flags: number): string;
+    static buildYesContent(width: number, height: number, flags: number | PdfFormFieldFlags): PdfButtonAppearanceStream;
 }

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

@@ -0,0 +1,58 @@
+import { PdfDictionary } from '../../core/objects/pdf-dictionary.js';
+import { PdfAppearanceStream } from './pdf-appearance-stream.js';
+import { PdfGraphics } from './pdf-graphics.js';
+import { PdfFont } from '../../fonts/pdf-font.js';
+import { PdfFormFieldFlags } from '../fields/pdf-form-field-flags.js';
+/**
+ * Appearance stream for button fields (checkboxes, radio buttons).
+ */
+export class PdfButtonAppearanceStream extends PdfAppearanceStream {
+    constructor(ctx) {
+        const resources = new PdfDictionary();
+        const fonts = new PdfDictionary();
+        fonts.set('ZaDb', PdfFont.ZAPF_DINGBATS.dict.clone());
+        resources.set('Font', fonts);
+        super({
+            width: ctx.width,
+            height: ctx.height,
+            contentStream: ctx.contentStream,
+            resources,
+        });
+    }
+    static buildYesContent(width, height, flags) {
+        const size = Math.min(width, height);
+        const isRadio = new PdfFormFieldFlags(flags).radio;
+        const g = new PdfGraphics();
+        if (isRadio) {
+            const center = size / 2;
+            const radius = size * 0.35;
+            const k = 0.5522847498;
+            const kRadius = k * radius;
+            g.save();
+            g.setFillRGB(0, 0, 0);
+            g.movePath(center, center + radius);
+            g.curveTo(center + kRadius, center + radius, center + radius, center + kRadius, center + radius, center);
+            g.curveTo(center + radius, center - kRadius, center + kRadius, center - radius, center, center - radius);
+            g.curveTo(center - kRadius, center - radius, center - radius, center - kRadius, center - radius, center);
+            g.curveTo(center - radius, center + kRadius, center - kRadius, center + radius, center, center + radius);
+            g.fill();
+            g.restore();
+        }
+        else {
+            const checkSize = size * 0.8;
+            const offset = (size - checkSize) / 2;
+            g.save();
+            g.beginText();
+            g.setFont('ZaDb', checkSize);
+            g.moveTo(offset, offset);
+            g.showLiteralText('4'); // Checkmark character in Zapf Dingbats
+            g.endText();
+            g.restore();
+        }
+        return new PdfButtonAppearanceStream({
+            width,
+            height,
+            contentStream: g.build(),
+        });
+    }
+}

package/dist/acroform/appearance/pdf-choice-appearance-stream.d.ts

@@ -0,0 +1,22 @@
+import { PdfDefaultAppearance } from '../fields/pdf-default-appearance.js';
+import { PdfAppearanceStream } from './pdf-appearance-stream.js';
+import type { PdfDictionary } from '../../core/objects/pdf-dictionary.js';
+import type { PdfFont } from '../../fonts/pdf-font.js';
+import { PdfFormFieldFlags } from '../fields/pdf-form-field-flags.js';
+/**
+ * Appearance stream for choice fields (dropdowns, list boxes).
+ */
+export declare class PdfChoiceAppearanceStream extends PdfAppearanceStream {
+    constructor(ctx: {
+        rect: [number, number, number, number];
+        value: string;
+        da: PdfDefaultAppearance;
+        flags: number | PdfFormFieldFlags;
+        fontResources?: PdfDictionary;
+        resolvedFonts?: Map<string, PdfFont>;
+        isUnicode?: boolean;
+        reverseEncodingMap?: Map<string, number>;
+        displayOptions?: string[];
+        selectedIndex?: number;
+    });
+}

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

@@ -0,0 +1,75 @@
+import { PdfAppearanceStream } from './pdf-appearance-stream.js';
+import { PdfGraphics } from './pdf-graphics.js';
+import { PdfFormFieldFlags } from '../fields/pdf-form-field-flags.js';
+/**
+ * Appearance stream for choice fields (dropdowns, list boxes).
+ */
+export class PdfChoiceAppearanceStream extends PdfAppearanceStream {
+    constructor(ctx) {
+        const [x1, y1, x2, y2] = ctx.rect;
+        const width = x2 - x1;
+        const height = y2 - y1;
+        super({
+            width,
+            height,
+            resources: ctx.fontResources,
+        });
+        const isUnicode = ctx.isUnicode ?? false;
+        const reverseEncodingMap = ctx.reverseEncodingMap;
+        const padding = 2;
+        const isCombo = new PdfFormFieldFlags(ctx.flags).combo;
+        const g = new PdfGraphics({ resolvedFonts: ctx.resolvedFonts });
+        g.beginMarkedContent();
+        g.save();
+        if (!isCombo && ctx.displayOptions && ctx.displayOptions.length > 0) {
+            // Listbox: render all items, highlight the selected one
+            const lineHeight = ctx.da.fontSize + 4;
+            const selectedIndex = ctx.selectedIndex ?? -1;
+            for (let i = 0; i < ctx.displayOptions.length; i++) {
+                const itemY = height - (i + 1) * lineHeight;
+                // Stop rendering if we've gone below the visible area
+                if (itemY + lineHeight < 0)
+                    break;
+                if (i === selectedIndex) {
+                    // Draw highlight background using the PDF re (rectangle) operator
+                    g.save();
+                    g.setFillRGB(0.376, 0.62, 0.671);
+                    g.raw(`0 ${itemY} ${width} ${lineHeight} re`);
+                    g.fill();
+                    g.restore();
+                }
+                const textY = itemY + lineHeight * 0.25;
+                g.beginText();
+                g.setDefaultAppearance(ctx.da);
+                g.moveTo(padding, textY);
+                g.showText(ctx.displayOptions[i], isUnicode, reverseEncodingMap);
+                g.endText();
+            }
+        }
+        else {
+            // Combo (dropdown) or no options: show selected value only
+            const textY = (height - ctx.da.fontSize) / 2 + ctx.da.fontSize * 0.2;
+            g.beginText();
+            g.setDefaultAppearance(ctx.da);
+            g.moveTo(padding, textY);
+            g.showText(ctx.value, isUnicode, reverseEncodingMap);
+            g.endText();
+            if (isCombo) {
+                const arrowWidth = height * 0.8;
+                const arrowX = width - arrowWidth - 2;
+                const arrowY = height / 2;
+                const arrowSize = height * 0.3;
+                g.save();
+                g.setFillGray(0.5);
+                g.movePath(arrowX + arrowWidth / 2, arrowY - arrowSize / 3);
+                g.lineTo(arrowX + arrowWidth / 2 - arrowSize / 2, arrowY + arrowSize / 3);
+                g.lineTo(arrowX + arrowWidth / 2 + arrowSize / 2, arrowY + arrowSize / 3);
+                g.fill();
+                g.restore();
+            }
+        }
+        g.restore();
+        g.endMarkedContent();
+        this.graphics = g;
+    }
+}

package/dist/acroform/appearance/pdf-graphics.d.ts

@@ -0,0 +1,51 @@
+import type { PdfDefaultAppearance } from '../fields/pdf-default-appearance.js';
+import { PdfFont } from '../../fonts/pdf-font.js';
+/**
+ * Lightweight builder for PDF content streams.
+ * Chains PDF operators via a fluent API and emits the final stream with build().
+ * Enhanced with text measurement capabilities for layout calculations.
+ */
+export declare class PdfGraphics {
+    private lines;
+    private resolvedFonts?;
+    private defaultAppearance?;
+    constructor(options?: {
+        resolvedFonts?: Map<string, PdfFont>;
+        defaultAppearance?: PdfDefaultAppearance;
+    });
+    save(): this;
+    restore(): this;
+    beginText(): this;
+    endText(): this;
+    setDefaultAppearance(da: PdfDefaultAppearance): this;
+    moveTo(x: number, y: number): this;
+    showText(text: string, isUnicode: boolean, reverseEncodingMap?: Map<string, number>): this;
+    showLiteralText(text: string): this;
+    beginMarkedContent(): this;
+    endMarkedContent(): this;
+    raw(op: string): this;
+    setFillRGB(r: number, g: number, b: number): this;
+    setFillGray(v: number): this;
+    setFont(name: string, size: number): this;
+    movePath(x: number, y: number): this;
+    lineTo(x: number, y: number): this;
+    curveTo(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number): this;
+    fill(): this;
+    stroke(): this;
+    closePath(): this;
+    build(): string;
+    private get currentFont();
+    /**
+     * Calculate the width of text using the current font and size.
+     */
+    measureTextWidth(text: string, fontSize?: number): number;
+    /**
+     * Wrap text to fit within the specified width, breaking at word boundaries.
+     */
+    wrapTextToLines(text: string, maxWidth: number, fontSize?: number): string[];
+    /**
+     * Calculate the minimum font size needed to fit text within given constraints.
+     */
+    calculateFittingFontSize(text: string, maxWidth: number, maxHeight?: number, lineHeight?: number): number;
+    private breakLongWord;
+}