Add documentation

src/BaselineRatio.ts

@@ -1,3 +1,4 @@
+/** Helper method to calculate the ratio between the top of the font to its baseline and its baseline to the bottom of the font. */
 export const baselineRatio = (
   fontFamily: string,
   fontSizePx: number

src/ColorUtils.ts

@@ -20,7 +20,6 @@ export class ColorUtils {
       };
     }
 
-    // Return a default or handle the case when parsing fails
     return null;
   }
 

src/FormInputValues.ts

@@ -1,3 +1,4 @@
+/** Container for the values for all form elements for a PDF. */
 export class FormInputValues {
   public readonly textNameToValue: Map<string, string> = new Map();
   public readonly checkboxNameToValue: Map<string, boolean> = new Map();

src/Main.ts

@@ -417,6 +417,9 @@ function onPageLoad() {
           textOverlay.textSize = fontSizePx * originalToActualRatio;
           textOverlay.fontFamily = draggable.fontFamily;
           const [offsetLeft, offsetTop] = draggable.offsetToAncestor;
+          // To calculate the text overlay position, we need to account for the fact that
+          // pdf-js requires the coordinates from the font baseline. Thus we need to
+          // calculate it ourselves.
           textOverlay.transform.x =
             (2 + offsetLeft + (2 + offsetLeft) / page.offsetWidth) *
             originalToActualRatio;
@@ -446,6 +449,7 @@ function onPageLoad() {
       }
     }
 
+    /** Applies a matrix transformation on the `Transform` object to be aligned with the `PdfPage`. */
     function adjustTransformToPageRotation(
       transform: Transform,
       pdfPage: PdfPage

src/PdfDocument.ts

@@ -6,6 +6,7 @@ import { PdfDocumentSaver } from "./PdfDocumentSaver";
 import { FormInputValues } from "./FormInputValues";
 import { Overlays } from "./overlays/Overlays";
 
+/** Represents a PDF document, providing methods to load and save PDFs. */
 export class PdfDocument {
   private pageCache: Map<number, PdfPage>;
 

src/PdfDocumentLoader.ts

@@ -1,6 +1,7 @@
 import * as pdfjsLib from "pdfjs-dist";
 import { PdfDocument } from "./PdfDocument";
 
+/** Helper which loads a PDF file from the supplied `fileData`. */
 export class PdfDocumentLoader {
   constructor(
     private readonly fileData: ArrayBuffer,
@@ -10,7 +11,6 @@ export class PdfDocumentLoader {
   public async load(): Promise<PdfDocument> {
     const loadingTask = pdfjsLib.getDocument({
       data: this.fileData,
-      //url: this.url,
       cMapUrl: this.options.cMapUrl,
       cMapPacked: this.options.cMapPacked,
       enableXfa: this.options.enableXfa,
@@ -21,8 +21,8 @@ export class PdfDocumentLoader {
   }
 }
 
+/** PDF options for loading a PDF, such as the cMap URL. */
 export class PdfOptions {
-  // TODO: make these private
   constructor(
     readonly cMapUrl?: string,
     readonly cMapPacked: boolean = false,

src/PdfDocumentSaver.ts

@@ -14,9 +14,11 @@ import { ImageType } from "./overlays/ImageOverlay";
 import { Overlays } from "./overlays/Overlays";
 import { PageOverlays } from "./overlays/PageOverlays";
 
+/** Helper which applies all changes made to a PDF and saves them into a new PDF. */
 export class PdfDocumentSaver {
   constructor() {}
 
+  /** Returns a `Uint8Array` which represents a PDF with all user-made changes applied, such as filled PDF forms, added overlays, page rotations. */
   public async applyChangesAndSave(
     originalPdfBytes: Uint8Array,
     formInputValues: FormInputValues,
@@ -27,9 +29,6 @@ export class PdfDocumentSaver {
 
     this.populateFormValues(formInputValues, pdfDoc.getForm());
 
-    // TODO: validation
-    // TODO: refactor
-
     const neededFonts: Map<string, PDFFont> = await this.getNeededFonts(
       overlays,
       pdfDoc
@@ -43,9 +42,7 @@ export class PdfDocumentSaver {
       this.doImageDrawing(pageOverlays, page, base64ToPdfImageMap);
     }
 
-    //if (rotateBy != 0) {
     this.rotatePages(pdfDoc, rotateBy);
-    //}
 
     return pdfDoc.save();
   }
@@ -133,6 +130,7 @@ export class PdfDocumentSaver {
     }
   }
 
+  /** Populates the form fields in the PDF with any changes the user has done. */
   private populateFormValues(formInputValues: FormInputValues, form: PDFForm) {
     for (const [key, value] of formInputValues.textNameToValue) {
       try {
@@ -209,6 +207,7 @@ export class PdfDocumentSaver {
     }
   }
 
+  /** Returns any fonts that need to be embedded into the PDF. */
   private async getNeededFonts(overlays: Overlays, pdfDoc: PDFDocument) {
     const fontValues: string[] = Object.values(StandardFonts);
     const neededFonts: Map<string, PDFFont> = new Map();

src/PdfPage.ts

@@ -1,6 +1,7 @@
 import * as pdfjsLib from "pdfjs-dist";
 import { EventBus, PDFPageView } from "pdfjs-dist/web/pdf_viewer";
 
+/** Represents a PDF page, providing methods to render pages and thumbnails. */
 export class PdfPage {
   constructor(
     private readonly pdfPageProxy: pdfjsLib.PDFPageProxy,

src/RGB.ts

@@ -1,3 +1,4 @@
+/** Represents a color. */
 export interface RGB {
   red: number;
   green: number;

src/View.ts

@@ -3,6 +3,7 @@ import { ImageDraggableMetadata } from "./draggables/ImageDraggableMetadata";
 import { PdfPage } from "./PdfPage";
 import { TextDraggableMetadata } from "./draggables/TextDraggableMetadata";
 
+/** View which is responsible for displaying the data from the controller. */
 export class View {
   public readonly container: HTMLDivElement = document.getElementById(
     "pageContainer"
@@ -98,6 +99,7 @@ export class View {
       onClickListener;
   }
 
+  /** Updates the page number wherever relevant (such as the thumbnails) as the user scrolls. */
   public setOnContentScrollEventListener(
     scrollEvent: (currentPage: number) => void
   ) {
@@ -296,7 +298,8 @@ export class View {
       };
   }
 
-  public extractFormInputValues() {
+  /** Iterates through all form fields in the PDF and returns them as a `FormInputValues` object. */
+  public extractFormInputValues(): FormInputValues {
     const that = this;
     const formInputValues: FormInputValues = new FormInputValues();
 
@@ -338,6 +341,9 @@ export class View {
         (radioButton) => (radioButton as HTMLInputElement).checked
       );
       if (selected != null) {
+        // pdfjs doesn't necessarily add form fields in the same order as
+        // in the original PDF. Instead we rely on the zIndex which is in
+        // the correct order.
         var minZIndex = that.calculateSmallestZIndex(
           radioButtons.map((el) => el.parentElement as HTMLElement)
         );
@@ -597,6 +603,7 @@ export class View {
     }
   }
 
+  /** Sets up the draggable overlay's button options and dragging. */
   private setupDraggable(
     draggableElement: HTMLElement,
     numDraggables: number

src/draggables/ImageDraggableMetadata.ts

@@ -1,3 +1,4 @@
+/** Wrapper for data needed to create an `ImageOverlay`. */
 export class ImageDraggableMetadata {
   public imageBase64: string;
   public scaledSize: [number, number];

src/draggables/TextDraggableMetadata.ts

@@ -1,3 +1,4 @@
+/** Wrapper for data needed to create a `TextOverlay`. */
 export class TextDraggableMetadata {
   public textInput: HTMLInputElement;
   public text: string;

src/overlays/ImageOverlay.ts

@@ -1,10 +1,18 @@
 import { OverlayBase } from "./OverlayBase";
 
+/**
+ * Enumerates the supported image types.
+ */
 export enum ImageType {
   PNG,
   JPEG,
 }
 
+/**
+ * An overlay which describes an image, such as its base64 string representation, the image type, size, etc.
+ *
+ * @extends OverlayBase
+ */
 export class ImageOverlay extends OverlayBase {
   base64: string;
   imageType: ImageType;

src/overlays/OverlayBase.ts

@@ -1,5 +1,6 @@
 import { Transform } from "./Transform";
 
+/** Base class that describes an overlay - an object that is added on top of a PDF page, such as image, or text. */
 export class OverlayBase {
   public readonly transform: Transform = new Transform();
 }

src/overlays/Overlays.ts

@@ -1,5 +1,6 @@
 import { PageOverlays } from "./PageOverlays";
 
+/** Container of `PageOverlays` mapped to their page numbers. */
 export class Overlays {
   public readonly pagesOverlays: Map<number, PageOverlays> = new Map();
 }

src/overlays/PageOverlays.ts

@@ -1,6 +1,7 @@
 import { TextOverlay } from "./TextOverlay";
 import { ImageOverlay } from "./ImageOverlay";
 
+/** Container for the different kinds of supported overlays, such as text or images. */
 export class PageOverlays {
   public readonly textOverlays: TextOverlay[] = [];
   public readonly imageOverlays: ImageOverlay[] = [];

src/overlays/TextOverlay.ts

@@ -2,6 +2,11 @@ import { ColorUtils } from "../ColorUtils";
 import { RGB } from "../RGB";
 import { OverlayBase } from "./OverlayBase";
 
+/**
+ * An overlay which describes a text label, such as its text, font size, color, etc.
+ *
+ * @extends OverlayBase
+ */
 export class TextOverlay extends OverlayBase {
   public text: string = "";
 

src/overlays/Transform.ts

@@ -1,3 +1,4 @@
+/** Data object which describes a transformation, such as the X and Y coordinates and the rotation. */
 export class Transform {
   public x: number = 0;
   public y: number = 0;