feat(forms): add removeField method to delete form fields

Adds the ability to remove individual form fields from a PDF document.
The method removes the field from the AcroForm and all associated widget
annotations from their respective pages.

Author: Mythie

src/api/pdf-form.test.ts

@@ -678,3 +678,153 @@ describe("drawField", () => {
     expect(checkbox2!.isChecked()).toBe(true);
   });
 });
+
+describe("removeField", () => {
+  it("removes a field by instance", async () => {
+    const pdf = PDF.create();
+    pdf.addPage({ size: "letter" });
+    const form = pdf.getOrCreateForm();
+    const page = pdf.getPage(0);
+
+    const field = form.createTextField("name");
+    page!.drawField(field, { x: 100, y: 700, width: 200, height: 24 });
+
+    expect(form.hasField("name")).toBe(true);
+    expect(form.fieldCount).toBe(1);
+
+    const removed = form.removeField(field);
+
+    expect(removed).toBe(true);
+    expect(form.hasField("name")).toBe(false);
+    expect(form.fieldCount).toBe(0);
+    expect(form.getField("name")).toBeUndefined();
+  });
+
+  it("removes a field by name", async () => {
+    const pdf = PDF.create();
+    pdf.addPage({ size: "letter" });
+    const form = pdf.getOrCreateForm();
+    const page = pdf.getPage(0);
+
+    form.createTextField("email");
+    page!.drawField(form.getTextField("email")!, { x: 100, y: 700, width: 200, height: 24 });
+
+    const removed = form.removeField("email");
+
+    expect(removed).toBe(true);
+    expect(form.hasField("email")).toBe(false);
+  });
+
+  it("returns false for non-existent field", async () => {
+    const pdf = PDF.create();
+    const form = pdf.getOrCreateForm();
+
+    const removed = form.removeField("nonexistent");
+
+    expect(removed).toBe(false);
+  });
+
+  it("removes widget annotations from page", async () => {
+    const pdf = PDF.create();
+    pdf.addPage({ size: "letter" });
+    const form = pdf.getOrCreateForm();
+    const page = pdf.getPage(0);
+
+    const field = form.createTextField("name");
+    page!.drawField(field, { x: 100, y: 700, width: 200, height: 24 });
+
+    // Verify widget was added
+    expect(field.getWidgets()).toHaveLength(1);
+
+    form.removeField(field);
+
+    // After removal, the page should not have form field annotations
+    // We can verify by saving and reloading
+    const bytes = await pdf.save();
+    const pdf2 = await PDF.load(bytes);
+    const form2 = pdf2.getForm();
+
+    // Form should exist but be empty
+    if (form2) {
+      expect(form2.fieldCount).toBe(0);
+    }
+  });
+
+  it("removes field with multiple widgets across pages", async () => {
+    const pdf = PDF.create();
+    pdf.addPage({ size: "letter" });
+    pdf.addPage({ size: "letter" });
+    const form = pdf.getOrCreateForm();
+    const page1 = pdf.getPage(0);
+    const page2 = pdf.getPage(1);
+
+    const field = form.createTextField("sharedField");
+    page1!.drawField(field, { x: 100, y: 700, width: 200, height: 24 });
+    page2!.drawField(field, { x: 50, y: 500, width: 300, height: 30 });
+
+    expect(field.getWidgets()).toHaveLength(2);
+
+    form.removeField(field);
+
+    expect(form.hasField("sharedField")).toBe(false);
+    expect(form.fieldCount).toBe(0);
+  });
+
+  it("allows creating a new field with the same name after removal", async () => {
+    const pdf = PDF.create();
+    pdf.addPage({ size: "letter" });
+    const form = pdf.getOrCreateForm();
+    const page = pdf.getPage(0);
+
+    const field1 = form.createTextField("name", { defaultValue: "First" });
+    page!.drawField(field1, { x: 100, y: 700, width: 200, height: 24 });
+
+    form.removeField(field1);
+
+    // Should be able to create a new field with the same name
+    const field2 = form.createTextField("name", { defaultValue: "Second" });
+    page!.drawField(field2, { x: 100, y: 700, width: 200, height: 24 });
+
+    expect(form.hasField("name")).toBe(true);
+    expect(form.getTextField("name")?.getValue()).toBe("Second");
+  });
+
+  it("removes existing field from loaded PDF", async () => {
+    const bytes = await loadFixture("forms", "sample_form.pdf");
+    const pdf = await PDF.load(bytes);
+    const form = pdf.getForm();
+
+    const initialCount = form!.fieldCount;
+    const fieldToRemove = form!.getFields()[0];
+    const fieldName = fieldToRemove.name;
+
+    const removed = form!.removeField(fieldToRemove);
+
+    expect(removed).toBe(true);
+    expect(form!.hasField(fieldName)).toBe(false);
+    expect(form!.fieldCount).toBe(initialCount - 1);
+  });
+
+  it("persists removal through save/load cycle", async () => {
+    const pdf = PDF.create();
+    pdf.addPage({ size: "letter" });
+    const form = pdf.getOrCreateForm();
+    const page = pdf.getPage(0);
+
+    form.createTextField("keep");
+    form.createTextField("remove");
+    page!.drawField(form.getTextField("keep")!, { x: 100, y: 700, width: 200, height: 24 });
+    page!.drawField(form.getTextField("remove")!, { x: 100, y: 650, width: 200, height: 24 });
+
+    form.removeField("remove");
+
+    const bytes = await pdf.save();
+    const pdf2 = await PDF.load(bytes);
+    const form2 = pdf2.getForm();
+
+    expect(form2).not.toBeNull();
+    expect(form2!.fieldCount).toBe(1);
+    expect(form2!.hasField("keep")).toBe(true);
+    expect(form2!.hasField("remove")).toBe(false);
+  });
+});

src/api/pdf-form.ts

@@ -60,6 +60,7 @@ import { PdfArray } from "#src/objects/pdf-array";
 import { PdfDict } from "#src/objects/pdf-dict";
 import { PdfName } from "#src/objects/pdf-name";
 import { PdfNumber } from "#src/objects/pdf-number";
+import { PdfRef } from "#src/objects/pdf-ref";
 import { PdfString } from "#src/objects/pdf-string";
 
 import type { PDFContext } from "./pdf-context";
@@ -961,6 +962,130 @@ export class PDFForm {
     return field;
   }
 
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Field Removal
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Remove a form field from the document.
+   *
+   * This removes the field from the AcroForm and all its widget annotations
+   * from their respective pages.
+   *
+   * @param fieldOrName - The field instance or field name to remove
+   * @returns true if the field was found and removed, false otherwise
+   *
+   * @example
+   * ```typescript
+   * // Remove by field instance
+   * const nameField = form.getTextField("name");
+   * form.removeField(nameField);
+   *
+   * // Remove by name
+   * form.removeField("email");
+   * ```
+   */
+  removeField(fieldOrName: FormField | string): boolean {
+    // Resolve field from name if needed
+    const field =
+      typeof fieldOrName === "string" ? this.fieldsByName.get(fieldOrName) : fieldOrName;
+
+    if (!field) {
+      return false;
+    }
+
+    const fieldRef = field.getRef();
+
+    if (!fieldRef) {
+      return false;
+    }
+
+    // Remove widgets from their pages
+    this.removeWidgetsFromPages(field);
+
+    // Remove field from AcroForm's /Fields array
+    const removed = this._acroForm.removeField(fieldRef);
+
+    if (removed) {
+      // Update internal caches
+      this.allFields = this.allFields.filter(f => f !== field);
+      this.fieldsByName.delete(field.name);
+    }
+
+    return removed;
+  }
+
+  /**
+   * Remove all widgets of a field from their respective pages.
+   */
+  private removeWidgetsFromPages(field: FormField): void {
+    const widgets = field.getWidgets();
+    const pageRefs = this._ctx.pages.getPages();
+
+    // Build a set of widget refs for fast lookup
+    const widgetRefKeys = new Set<string>();
+
+    for (const widget of widgets) {
+      if (widget.ref) {
+        widgetRefKeys.add(`${widget.ref.objectNumber} ${widget.ref.generation}`);
+      }
+    }
+
+    if (widgetRefKeys.size === 0) {
+      return;
+    }
+
+    // Scan pages and remove widget annotations
+    for (const pageRef of pageRefs) {
+      const pageDict = this._ctx.registry.resolve(pageRef);
+
+      if (!(pageDict instanceof PdfDict)) {
+        continue;
+      }
+
+      const annotsEntry = pageDict.get("Annots");
+
+      if (!annotsEntry) {
+        continue;
+      }
+
+      let annots: PdfArray | null = null;
+
+      if (annotsEntry instanceof PdfArray) {
+        annots = annotsEntry;
+      } else if (annotsEntry instanceof PdfRef) {
+        const resolved = this._ctx.registry.resolve(annotsEntry);
+
+        if (resolved instanceof PdfArray) {
+          annots = resolved;
+        }
+      }
+
+      if (!annots) {
+        continue;
+      }
+
+      // Remove matching widget refs from this page's annotations
+      // Iterate backwards to safely remove items
+      for (let i = annots.length - 1; i >= 0; i--) {
+        const item = annots.at(i);
+
+        if (item instanceof PdfRef) {
+          const key = `${item.objectNumber} ${item.generation}`;
+
+          if (widgetRefKeys.has(key)) {
+            annots.remove(i);
+          }
+        }
+      }
+
+      // If annots is now empty, remove the /Annots entry
+      if (annots.length === 0) {
+        pageDict.delete("Annots");
+      }
+    }
+  }
+
   // ─────────────────────────────────────────────────────────────────────────────
   // Field Creation Helpers
   // ─────────────────────────────────────────────────────────────────────────────

src/document/forms/acro-form.ts

@@ -765,6 +765,37 @@ export class AcroForm implements AcroFormLike {
     this.clearCache();
   }
 
+  /**
+   * Remove a field reference from the Fields array.
+   *
+   * This only removes the field from the AcroForm's /Fields array.
+   * Widget removal from pages must be handled separately.
+   *
+   * @param fieldRef Reference to the field dictionary to remove
+   * @returns true if the field was found and removed, false otherwise
+   */
+  removeField(fieldRef: PdfRef): boolean {
+    const fieldsArray = this.dict.getArray("Fields");
+
+    if (!fieldsArray) {
+      return false;
+    }
+
+    // Find and remove the field reference
+    for (let i = 0; i < fieldsArray.length; i++) {
+      const item = fieldsArray.at(i);
+
+      if (item instanceof PdfRef && item === fieldRef) {
+        fieldsArray.remove(i);
+        this.clearCache();
+
+        return true;
+      }
+    }
+
+    return false;
+  }
+
   // ─────────────────────────────────────────────────────────────────────────────
   // Form Flattening
   // ─────────────────────────────────────────────────────────────────────────────