pdf-lite 1.0.4 → 1.0.6

package/EXAMPLES.md

@@ -915,6 +915,18 @@ function createTextField(
     // Default appearance string (font and size)
     fieldDict.set('DA', new PdfString('/Helv 12 Tf 0 g'))
 
+    // Border style (solid, 1pt width)
+    const borderDict = new PdfDictionary()
+    borderDict.set('W', new PdfNumber(1))
+    borderDict.set('S', new PdfName('S'))
+    fieldDict.set('BS', borderDict)
+
+    // Appearance characteristics
+    const mkDict = new PdfDictionary()
+    mkDict.set('BC', new PdfArray([new PdfNumber(0)])) // Border color (black)
+    mkDict.set('BG', new PdfArray([new PdfNumber(1)])) // Background color (white)
+    fieldDict.set('MK', mkDict)
+
     return new PdfIndirectObject({ content: fieldDict })
 }
 
@@ -951,6 +963,18 @@ function createCheckboxField(
     fieldDict.set('V', new PdfName(checked ? 'Yes' : 'Off'))
     fieldDict.set('AS', new PdfName(checked ? 'Yes' : 'Off'))
 
+    // Border style
+    const borderDict = new PdfDictionary()
+    borderDict.set('W', new PdfNumber(1))
+    borderDict.set('S', new PdfName('S'))
+    fieldDict.set('BS', borderDict)
+
+    // Appearance characteristics
+    const mkDict = new PdfDictionary()
+    mkDict.set('BC', new PdfArray([new PdfNumber(0)])) // Border color (black)
+    mkDict.set('BG', new PdfArray([new PdfNumber(1)])) // Background color (white)
+    fieldDict.set('MK', mkDict)
+
     return new PdfIndirectObject({ content: fieldDict })
 }
 
@@ -978,7 +1002,7 @@ const contentStream = new PdfIndirectObject({
 0 -30 Td (Email:) Tj
 0 -30 Td (Phone:) Tj
 0 -30 Td (Subscribe to newsletter:) Tj
-ET`,
+ET `,
     }),
 })
 document.add(contentStream)
@@ -1041,7 +1065,8 @@ acroForm.set(
         subscribeField.reference,
     ]),
 )
-// NeedAppearances flag tells PDF readers to generate appearance streams
+// With appearance streams provided, we don't need NeedAppearances
+// This prevents Acrobat from modifying the PDF on open
 acroForm.set('NeedAppearances', new PdfBoolean(true))
 
 // Default resources for the form (font)
@@ -1051,9 +1076,12 @@ const helveticaFont = new PdfDictionary()
 helveticaFont.set('Type', new PdfName('Font'))
 helveticaFont.set('Subtype', new PdfName('Type1'))
 helveticaFont.set('BaseFont', new PdfName('Helvetica'))
-formFontDict.set('Helv', helveticaFont)
+const helveticaFontObj = new PdfIndirectObject({ content: helveticaFont })
+document.add(helveticaFontObj)
+formFontDict.set('Helv', helveticaFontObj.reference)
 formResources.set('Font', formFontDict)
 acroForm.set('DR', formResources)
+acroForm.set('DA', new PdfString('/Helv 12 Tf 0 g'))
 
 const acroFormObj = new PdfIndirectObject({ content: acroForm })
 document.add(acroFormObj)
@@ -1081,90 +1109,12 @@ 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])
 
-// Get the catalog reference from trailer
-const catalogRef = filledDocument.trailerDict.get('Root')
-if (!catalogRef || !(catalogRef instanceof PdfObjectReference)) {
-    throw new Error('No catalog found in PDF')
-}
-
-// Read the catalog object
-const catalogObj = await filledDocument.readObject({
-    objectNumber: catalogRef.objectNumber,
-})
-if (!catalogObj || !(catalogObj.content instanceof PdfDictionary)) {
-    throw new Error('Catalog object not found')
-}
-
-// Get the AcroForm reference
-const acroFormRef = catalogObj.content.get('AcroForm')
-if (!acroFormRef || !(acroFormRef instanceof PdfObjectReference)) {
-    throw new Error('No AcroForm found in PDF')
-}
-
-// Read the AcroForm object
-const filledAcroFormObj = await filledDocument.readObject({
-    objectNumber: acroFormRef.objectNumber,
+await filledDocument.acroForm.setFieldValues({
+    name: 'John Doe',
+    email: 'john.doe@example.com',
+    phone: '+1 (555) 123-4567',
+    subscribe: 'Off', // For checkbox, use the "Yes/Off" value
 })
-if (
-    !filledAcroFormObj ||
-    !(filledAcroFormObj.content instanceof PdfDictionary)
-) {
-    throw new Error('AcroForm object not found')
-}
-
-// Get the fields array
-const fieldsArray = filledAcroFormObj.content.get('Fields')
-if (!fieldsArray || !(fieldsArray instanceof PdfArray)) {
-    throw new Error('No fields found in AcroForm')
-}
-
-// Helper function to find a field by name
-async function findField(
-    fieldName: string,
-): Promise<PdfIndirectObject<PdfDictionary> | null> {
-    for (const fieldRef of fieldsArray.items) {
-        if (!(fieldRef instanceof PdfObjectReference)) continue
-        const fieldObj = await filledDocument.readObject({
-            objectNumber: fieldRef.objectNumber,
-        })
-        if (!fieldObj || !(fieldObj.content instanceof PdfDictionary)) continue
-
-        const name = fieldObj.content.get('T')
-        if (name instanceof PdfString) {
-            // Convert bytes to string for comparison
-            const nameStr = name.value
-            if (nameStr === fieldName) {
-                return fieldObj as PdfIndirectObject<PdfDictionary>
-            }
-        }
-    }
-    return null
-}
-
-// Update the name field value
-const nameFieldObj = await findField('name')
-if (nameFieldObj) {
-    nameFieldObj.content.set('V', new PdfString('John Doe'))
-}
-
-// Update the email field value
-const emailFieldObj = await findField('email')
-if (emailFieldObj) {
-    emailFieldObj.content.set('V', new PdfString('john.doe@example.com'))
-}
-
-// Update the phone field value
-const phoneFieldObj = await findField('phone')
-if (phoneFieldObj) {
-    phoneFieldObj.content.set('V', new PdfString('+1 (555) 123-4567'))
-}
-
-// Check the subscribe checkbox
-const subscribeFieldObj = await findField('subscribe')
-if (subscribeFieldObj) {
-    subscribeFieldObj.content.set('V', new PdfName('Yes'))
-    subscribeFieldObj.content.set('AS', new PdfName('Yes'))
-}
 
 // Save the filled form
 await fs.writeFile(`${tmpFolder}/form-filled.pdf`, filledDocument.toBytes())
@@ -1174,7 +1124,7 @@ console.log('\nForm field values:')
 console.log('- Name: John Doe')
 console.log('- Email: john.doe@example.com')
 console.log('- Phone: +1 (555) 123-4567')
-console.log('- Subscribe: Yes')
+console.log('- Subscribe: Off')
 ```
 
 ## Tokeniser usage example

package/README.md

@@ -18,6 +18,93 @@ PRs and issues are welcome!
 - **Browser and Node.js support**: Works seamlessly in both environments, allowing for versatile usage.
 - **Low-level API**: Provides a low-level API for advanced users who want to manipulate PDF files directly, as well as a higher-level API for easier usage.
 
+## Installation
+
+```bash
+npm install pdf-lite
+yarn add pdf-lite
+pnpm add pdf-lite
+```
+
+## Usage
+
+The library provides both low-level and high-level APIs for working with PDF documents. See [PDF Support](#pdf-support) for a list of supported features.
+
+### Reading a PDF
+
+```typescript
+import { PdfReader } from 'pdf-lite/pdf/pdf-reader'
+import { readFile } from 'fs/promises'
+
+const pdfBytes = await readFile('document.pdf')
+const doc = await PdfReader.fromBytes([pdfBytes])
+```
+
+### Creating a PDF from Scratch
+
+```typescript
+import { PdfDocument } from 'pdf-lite/pdf/pdf-document'
+import { PdfDictionary } from 'pdf-lite/core/objects/pdf-dictionary'
+import { PdfIndirectObject } from 'pdf-lite/core/objects/pdf-indirect-object'
+import { PdfStream } from 'pdf-lite/core/objects/pdf-stream'
+import { PdfName } from 'pdf-lite/core/objects/pdf-name'
+import { PdfArray } from 'pdf-lite/core/objects/pdf-array'
+import { PdfNumber } from 'pdf-lite/core/objects/pdf-number'
+
+// Create the document
+const document = new PdfDocument()
+
+// Create content stream
+const contentStream = new PdfIndirectObject({
+    content: new PdfStream({
+        header: new PdfDictionary(),
+        original: 'BT /F1 24 Tf 100 700 Td (Hello, PDF-Lite!) Tj ET',
+    }),
+})
+
+// Create and commit objects
+document.commit(contentStream)
+// ... create pages, catalog, etc.
+
+// Output the PDF
+console.log(document.toString())
+```
+
+### Working with Encryption
+
+```typescript
+import { PdfDocument } from 'pdf-lite/pdf/pdf-document'
+import { PdfV2SecurityHandler } from 'pdf-lite/security/handlers/v2'
+
+const document = new PdfDocument()
+// ... build your PDF structure
+
+// Set up encryption
+document.securityHandler = new PdfV2SecurityHandler({
+    password: 'user-password',
+    documentId: 'unique-doc-id',
+    encryptMetadata: true,
+})
+
+// Encrypt the document
+await document.encrypt()
+
+console.log(document.toString())
+```
+
+### Signing PDFs
+
+```typescript
+import {
+    PdfAdbePkcs7DetachedSignatureObject,
+    PdfEtsiCadesDetachedSignatureObject,
+} from 'pdf-lite'
+
+// See examples directory for complete signing implementations
+```
+
+For more detailed examples, see the [EXAMPLES.md](EXAMPLES.md) file and the [examples/](examples/) directory.
+
 ## PDF Support
 
 ### Low-level PDF constructs
@@ -100,6 +187,22 @@ Long-Term Validation (LTV) support ensures that digital signatures remain valid
 - [x] Timestamping
 - [x] Verification of existing signatures
 
+### AcroForm filling
+
+Supports filling out AcroForm forms within PDF documents, allowing for dynamic content generation and user interaction.
+
+[x] Text fields
+[x] Checkboxes
+[x] Radio buttons
+[x] Dropdowns
+
+### XFA Forms
+
+You can read/write XFA XML data from PDFs, but rendering and filling XFA forms is not supported.
+
+[x] Read XFA XML
+[x] Write XFA XML
+
 ## Future Plans
 
 - **Writing Linearized PDF**: Writing linearized PDFs for faster web viewing, improving user experience when accessing documents online.
@@ -133,156 +236,13 @@ pnpm test:unit
 pnpm test:acceptance
 ```
 
-### Package Structure
-
-The main package (`packages/pdf-lite`) contains:
-
-- **src/core/** - Low-level PDF constructs (objects, parser, tokenizer)
-- **src/pdf/** - High-level PDF document handling
-- **src/signing/** - Digital signature support
-- **src/security/** - Encryption and security handlers
-- **src/filters/** - Compression/decompression filters
-
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
 
-## Installation
-
-```bash
-npm install pdf-lite
-```
-
-or
-
-```bash
-yarn add pdf-lite
-```
-
-or
-
-```bash
-pnpm add pdf-lite
-```
-
-## Usage
-
-The library provides both low-level and high-level APIs for working with PDF documents.
-
-### Reading a PDF
-
-```typescript
-import { PdfReader } from 'pdf-lite/pdf/pdf-reader'
-import { readFile } from 'fs/promises'
-
-const pdfBytes = await readFile('document.pdf')
-const doc = await PdfReader.fromBytes([pdfBytes])
-```
-
-### Creating a PDF from Scratch
-
-```typescript
-import { PdfDocument } from 'pdf-lite/pdf/pdf-document'
-import { PdfDictionary } from 'pdf-lite/core/objects/pdf-dictionary'
-import { PdfIndirectObject } from 'pdf-lite/core/objects/pdf-indirect-object'
-import { PdfStream } from 'pdf-lite/core/objects/pdf-stream'
-import { PdfName } from 'pdf-lite/core/objects/pdf-name'
-import { PdfArray } from 'pdf-lite/core/objects/pdf-array'
-import { PdfNumber } from 'pdf-lite/core/objects/pdf-number'
-
-// Create the document
-const document = new PdfDocument()
-
-// Create content stream
-const contentStream = new PdfIndirectObject({
-    content: new PdfStream({
-        header: new PdfDictionary(),
-        original: 'BT /F1 24 Tf 100 700 Td (Hello, PDF-Lite!) Tj ET',
-    }),
-})
-
-// Create and commit objects
-document.commit(contentStream)
-// ... create pages, catalog, etc.
-
-// Output the PDF
-console.log(document.toString())
-```
-
-### Working with Encryption
-
-```typescript
-import { PdfDocument } from 'pdf-lite/pdf/pdf-document'
-import { PdfV2SecurityHandler } from 'pdf-lite/security/handlers/v2'
-
-const document = new PdfDocument()
-// ... build your PDF structure
-
-// Set up encryption
-document.securityHandler = new PdfV2SecurityHandler({
-    password: 'user-password',
-    documentId: 'unique-doc-id',
-    encryptMetadata: true,
-})
-
-// Encrypt the document
-await document.encrypt()
-
-console.log(document.toString())
-```
-
-### Signing PDFs
-
-```typescript
-import {
-    PdfAdbePkcs7DetachedSignatureObject,
-    PdfEtsiCadesDetachedSignatureObject,
-} from 'pdf-lite'
-
-// See examples directory for complete signing implementations
-```
-
-For more detailed examples, see the [EXAMPLES.md](EXAMPLES.md) file and the [examples/](examples/) directory.
-
-## Project Structure
-
-This project is organized as a monorepo:
-
-- **packages/pdf-lite** - Main library package
-- **examples/** - Example scripts demonstrating library usage
-- **scripts/** - Build and development scripts
-
 ## API Reference
 
-The library uses TypeScript subpath exports for modular imports:
-
-```typescript
-// PDF Document
-import { PdfDocument } from 'pdf-lite/pdf/pdf-document'
-import { PdfReader } from 'pdf-lite/pdf/pdf-reader'
-
-// Core PDF objects
-import { PdfArray } from 'pdf-lite/core/objects/pdf-array'
-import { PdfDictionary } from 'pdf-lite/core/objects/pdf-dictionary'
-import { PdfStream } from 'pdf-lite/core/objects/pdf-stream'
-import { PdfString } from 'pdf-lite/core/objects/pdf-string'
-import { PdfName } from 'pdf-lite/core/objects/pdf-name'
-import { PdfNumber } from 'pdf-lite/core/objects/pdf-number'
-import { PdfIndirectObject } from 'pdf-lite/core/objects/pdf-indirect-object'
-import { PdfObjectReference } from 'pdf-lite/core/objects/pdf-object-reference'
-
-// Security
-import { PdfV2SecurityHandler } from 'pdf-lite/security/handlers/v2'
-
-// Signing
-import {
-    PdfAdbePkcs7DetachedSignatureObject,
-    PdfAdbePkcs7Sha1SignatureObject,
-    PdfAdbePkcsX509RsaSha1SignatureObject,
-    PdfEtsiCadesDetachedSignatureObject,
-    PdfEtsiRfc3161SignatureObject,
-} from 'pdf-lite'
-```
+See the [documentation folder](./docs/README.md) or the document site for a complete API reference.
 
 ## License
 

package/dist/acroform/acroform-manager.d.ts

@@ -0,0 +1,49 @@
+import { PdfDocument } from '../pdf/pdf-document.js';
+/**
+ * Manages AcroForm fields in PDF documents.
+ * Provides methods to read and write form field values.
+ */
+export declare class PdfAcroFormManager<T extends Record<string, string> = Record<string, string>> {
+    private document;
+    private _acroForm?;
+    constructor(document: PdfDocument);
+    /**
+     * Checks if the document contains AcroForm fields.
+     * @returns True if the document has AcroForm fields, false otherwise
+     */
+    hasAcroForm(): Promise<boolean>;
+    /**
+     * Gets all form field values as a key-value map.
+     * @returns Object with field names as keys and values as strings
+     */
+    getFieldValues(): Promise<T | null>;
+    /**
+     * Sets a form field value by field name.
+     * @param fieldName The name of the field to set
+     * @param value The value to set
+     * @throws Error if the field is not found
+     */
+    setFieldValues(newFields: Partial<T>): Promise<void>;
+    /**
+     * Gets the AcroForm indirect object from the document catalog.
+     * @returns The AcroForm indirect object or null if not found
+     */
+    private getAcroFormObject;
+    /**
+     * Gets the AcroForm dictionary from the document catalog.
+     * @returns The AcroForm dictionary or null if not found
+     */
+    private getAcroForm;
+    /**
+     * Recursively collects field values from the field tree.
+     */
+    private collectFieldValues;
+    /**
+     * Finds a field by its fully qualified name.
+     */
+    private findFieldByName;
+    /**
+     * Gets the fully qualified field name.
+     */
+    private getFieldName;
+}