Add support for text markup annotation

annotationsample-fixed.js

@@ -0,0 +1,71 @@
+//yarn node annotationsample-fixed.js
+const fs = require('fs');
+
+async function createAnnotatedPDF() {
+  try {
+    console.log('Creating PDF with annotation...');
+
+    // Import pdf-lib
+    const { PDFDocument, StandardFonts, rgb } = require('./cjs/index');
+    const {
+      AnnotationTypes,
+    } = require('./cjs/core/annotation/AnnotationTypes');
+
+    console.log('PDF-lib loaded successfully');
+
+    // Create a new PDF document
+    const pdfDoc = await PDFDocument.create();
+    const page = pdfDoc.addPage([600, 400]);
+    console.log('Page created');
+
+    // Add some text first
+    const helveticaFont = await pdfDoc.embedFont(StandardFonts.Helvetica);
+    page.drawText('This text will be highlighted', {
+      x: 50,
+      y: 300,
+      size: 12,
+      font: helveticaFont,
+      color: rgb(0, 0, 0),
+    });
+    console.log('Text added');
+
+    // Try to add a highlight annotation
+    try {
+      page.addTextMarkupAnnotation({
+        subtype: AnnotationTypes.Highlight,
+        color: [1, 1, 0], // Yellow
+        rect: {
+          x: 50,
+          y: 300,
+          width: 150,
+          height: 20,
+        },
+        contents: 'This is a highlight annotation',
+        quadPoints: {
+          leftbottomX: 50,
+          leftbottomY: 300,
+          lefttopX: 50,
+          lefttopY: 320,
+          righttopX: 200,
+          righttopY: 320,
+          rightbottomX: 200,
+          rightbottomY: 300,
+        },
+      });
+      console.log('Annotation added successfully');
+    } catch (annotationError) {
+      console.log('Could not add annotation:', annotationError.message);
+      console.log('Proceeding without annotation...');
+    }
+
+    // Save the PDF
+    const pdfBytes = await pdfDoc.save();
+    fs.writeFileSync('annotationsample.pdf', pdfBytes);
+    console.log('PDF created successfully: annotationsample.pdf');
+  } catch (error) {
+    console.error('Error creating PDF:', error);
+  }
+}
+
+// Run the function
+createAnnotatedPDF();

src/api/PDFPage.ts

@@ -33,6 +33,7 @@ import {
   PDFPageDrawTextOptions,
   BlendMode,
   PDFPageDrawSVGElementOptions,
+  PDFPageAddTextMarkupAnnotationOptions,
 } from './PDFPageOptions';
 import { degrees, Rotation, toDegrees } from './rotations';
 import { StandardFonts } from './StandardFonts';
@@ -45,6 +46,7 @@ import {
   PDFRef,
   PDFDict,
   PDFArray,
+  PDFAnnotation,
 } from '../core';
 import {
   assertEachIs,
@@ -59,6 +61,7 @@ import {
   assertIsOneOfOrUndefined,
 } from '../utils';
 import { drawSvg } from './svg';
+import { AnnotationFactory, PDFTextMarkupAnnotation } from '../core';
 
 /**
  * Represents a single page of a [[PDFDocument]].
@@ -1691,4 +1694,52 @@ export default class PDFPage {
       }
     }
   }
+
+  /**
+   * Read the annotation dictionaries from this page and convert to PDFAnnotation class instances
+   * @param pageLeaf The page leaf node
+   * @returns {PDFAnnotation[]} The annotations on this page
+   */
+  annotations(): PDFAnnotation[] {
+    const annotsArray = this.node.Annots();
+
+    // if there are no annotations...
+    if (!annotsArray || !(annotsArray instanceof PDFArray)) {
+      // ...return an empty array
+      return [];
+    }
+
+    // convert the annotation dictionaries to PDFAnnotation instances
+    const annotations: PDFAnnotation[] = [];
+    for (let i = 0; i < annotsArray.size(); i++) {
+      const annotDict = annotsArray.lookup(i);
+      if (annotDict instanceof PDFDict) {
+        const pdfAnnotation = AnnotationFactory.fromDict(annotDict);
+        annotations.push(pdfAnnotation);
+      }
+    }
+    return annotations;
+  }
+
+  /**
+   * Add an annotation to this page from an existing PDFAnnotation instance.
+   */
+  addTextMarkupAnnotation(
+    options: PDFPageAddTextMarkupAnnotationOptions,
+  ): PDFTextMarkupAnnotation {
+    const context = this.doc.context;
+    const page = this.node;
+
+    // convert to PDFDict
+    const annotation = PDFTextMarkupAnnotation.create(context, page, options);
+    const dict = annotation.dict;
+
+    // register PDF object into the PDF
+    const ref = context.register(dict);
+
+    // add the annotation to the page's Annots array
+    page.addAnnot(ref);
+
+    return annotation;
+  }
 }

src/api/PDFPageOptions.ts

@@ -3,6 +3,7 @@ import PDFFont from './PDFFont';
 import { Rotation } from './rotations';
 import { FillRule, LineCapStyle, TextRenderingMode } from './operators';
 import type { Space, TransformationMatrix } from '../types';
+import { AnnotationTypes } from '../core/annotation/AnnotationTypes';
 
 interface SvgOptions {
   matrix?: TransformationMatrix;
@@ -178,3 +179,44 @@ export interface PDFPageDrawSVGElementOptions {
   fonts?: { [fontName: string]: PDFFont };
   blendMode?: BlendMode;
 }
+
+/**
+ * Options for adding an annotation to a PDF page.
+ */
+export interface PDFPageAddAnnotationOptions {
+  subtype: AnnotationTypes;
+  rect: { x: number; y: number; width: number; height: number };
+  contents?: string;
+  name?: string;
+  flags?: number;
+  color?: number[];
+  border?: number[];
+  modificationDate?: Date;
+}
+
+/**
+ * Options for adding a markup annotation to a PDF page.
+ *
+ * Markup annotations refers:
+ * - Highlight
+ * - Underline
+ * - Squiggly
+ * - StrikeOut
+ * annotations.
+ */
+export interface PDFPageAddTextMarkupAnnotationOptions
+  extends PDFPageAddAnnotationOptions {
+  /**
+   * The quad points that define the region(s) to be marked up.
+   */
+  quadPoints: {
+    lefttopX: number;
+    lefttopY: number;
+    righttopX: number;
+    righttopY: number;
+    rightbottomX: number;
+    rightbottomY: number;
+    leftbottomX: number;
+    leftbottomY: number;
+  };
+}

src/core/annotation/AnnotationFactory.ts

@@ -0,0 +1,28 @@
+import PDFDict from '../objects/PDFDict';
+import PDFName from '../objects/PDFName';
+import PDFAnnotation from './PDFAnnotation';
+import PDFTextMarkupAnnotation from './PDFTextMarkupAnnotation';
+import { AnnotationTypes } from './AnnotationTypes';
+
+export default class AnnotationFactory {
+  static fromDict = (dict: PDFDict): PDFAnnotation => {
+    switch (this.getSubtype(dict)) {
+      case AnnotationTypes.Highlight:
+      case AnnotationTypes.Underline:
+      case AnnotationTypes.Squiggly:
+      case AnnotationTypes.StrikeOut:
+        return PDFTextMarkupAnnotation.fromDict(dict);
+      default:
+        return PDFAnnotation.fromDict(dict);
+    }
+  };
+
+  private static getSubtype(dict: PDFDict): AnnotationTypes | undefined {
+    const subtypePdfName = dict.lookup(PDFName.of('Subtype'), PDFName);
+    if (subtypePdfName instanceof PDFName) {
+      return subtypePdfName.toString() as AnnotationTypes;
+    } else {
+      return undefined;
+    }
+  }
+}

src/core/annotation/AnnotationTypes.ts

@@ -0,0 +1,31 @@
+/**
+ * Subtypes of PDF annotations from table 169 in the PDF specification.
+ */
+export enum AnnotationTypes {
+  Text = '/Text',
+  Link = '/Link',
+  FreeText = '/FreeText',
+  Line = '/Line',
+  Square = '/Square',
+  Circle = '/Circle',
+  Polygon = '/Polygon',
+  PolyLine = '/PolyLine',
+  Highlight = '/Highlight',
+  Underline = '/Underline',
+  Squiggly = '/Squiggly',
+  StrikeOut = '/StrikeOut',
+  Stamp = '/Stamp',
+  Caret = '/Caret',
+  Ink = '/Ink',
+  Popup = '/Popup',
+  FileAttachment = '/FileAttachment',
+  Sound = '/Sound',
+  Movie = '/Movie',
+  Widget = '/Widget',
+  Screen = '/Screen',
+  PrinterMark = '/PrinterMark',
+  TrapNet = '/TrapNet',
+  Watermark = '/Watermark',
+  ThreeD = '/3D',
+  Redact = '/Redact',
+}