@pdfme/pdf-lib 0.0.0

package/src/api/PDFPageOptions.ts

@@ -0,0 +1,175 @@
+import { Color } from './colors';
+import PDFFont from './PDFFont';
+import { Rotation } from './rotations';
+import { FillRule, LineCapStyle } from './operators';
+import type { Space, TransformationMatrix } from '../types';
+
+interface SvgOptions {
+  matrix?: TransformationMatrix;
+  clipSpaces?: Space[];
+}
+
+export enum BlendMode {
+  Normal = 'Normal',
+  Multiply = 'Multiply',
+  Screen = 'Screen',
+  Overlay = 'Overlay',
+  Darken = 'Darken',
+  Lighten = 'Lighten',
+  ColorDodge = 'ColorDodge',
+  ColorBurn = 'ColorBurn',
+  HardLight = 'HardLight',
+  SoftLight = 'SoftLight',
+  Difference = 'Difference',
+  Exclusion = 'Exclusion',
+}
+
+export interface PDFPageDrawTextOptions extends SvgOptions {
+  color?: Color;
+  opacity?: number;
+  blendMode?: BlendMode;
+  font?: PDFFont;
+  size?: number;
+  rotate?: Rotation;
+  xSkew?: Rotation;
+  ySkew?: Rotation;
+  x?: number;
+  y?: number;
+  lineHeight?: number;
+  maxWidth?: number;
+  wordBreaks?: string[];
+}
+
+export interface PDFPageDrawImageOptions extends SvgOptions {
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  rotate?: Rotation;
+  xSkew?: Rotation;
+  ySkew?: Rotation;
+  opacity?: number;
+  blendMode?: BlendMode;
+}
+
+export interface PDFPageDrawPageOptions {
+  x?: number;
+  y?: number;
+  xScale?: number;
+  yScale?: number;
+  width?: number;
+  height?: number;
+  rotate?: Rotation;
+  xSkew?: Rotation;
+  ySkew?: Rotation;
+  opacity?: number;
+  blendMode?: BlendMode;
+}
+
+export interface PDFPageDrawSVGOptions extends SvgOptions {
+  x?: number;
+  y?: number;
+  scale?: number;
+  rotate?: Rotation;
+  borderWidth?: number;
+  color?: Color;
+  opacity?: number;
+  borderColor?: Color;
+  borderOpacity?: number;
+  borderDashArray?: number[];
+  borderDashPhase?: number;
+  borderLineCap?: LineCapStyle;
+  blendMode?: BlendMode;
+  fillRule?: FillRule;
+}
+
+export interface PDFPageDrawLineOptions extends SvgOptions {
+  start: { x: number; y: number };
+  end: { x: number; y: number };
+  thickness?: number;
+  color?: Color;
+  opacity?: number;
+  lineCap?: LineCapStyle;
+  dashArray?: number[];
+  dashPhase?: number;
+  blendMode?: BlendMode;
+}
+
+export interface PDFPageDrawRectangleOptions extends SvgOptions {
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  rotate?: Rotation;
+  xSkew?: Rotation;
+  ySkew?: Rotation;
+  borderWidth?: number;
+  color?: Color;
+  opacity?: number;
+  borderColor?: Color;
+  borderOpacity?: number;
+  borderDashArray?: number[];
+  borderDashPhase?: number;
+  borderLineCap?: LineCapStyle;
+  blendMode?: BlendMode;
+  radius?: number;
+}
+
+export interface PDFPageDrawSquareOptions extends SvgOptions {
+  x?: number;
+  y?: number;
+  size?: number;
+  rotate?: Rotation;
+  xSkew?: Rotation;
+  ySkew?: Rotation;
+  borderWidth?: number;
+  color?: Color;
+  opacity?: number;
+  borderColor?: Color;
+  borderOpacity?: number;
+  borderDashArray?: number[];
+  borderDashPhase?: number;
+  borderLineCap?: LineCapStyle;
+  blendMode?: BlendMode;
+}
+
+export interface PDFPageDrawEllipseOptions extends SvgOptions {
+  x?: number;
+  y?: number;
+  xScale?: number;
+  yScale?: number;
+  rotate?: Rotation;
+  color?: Color;
+  opacity?: number;
+  borderColor?: Color;
+  borderOpacity?: number;
+  borderWidth?: number;
+  borderDashArray?: number[];
+  borderDashPhase?: number;
+  borderLineCap?: LineCapStyle;
+  blendMode?: BlendMode;
+}
+
+export interface PDFPageDrawCircleOptions extends SvgOptions {
+  x?: number;
+  y?: number;
+  size?: number;
+  color?: Color;
+  opacity?: number;
+  borderColor?: Color;
+  borderOpacity?: number;
+  borderWidth?: number;
+  borderDashArray?: number[];
+  borderDashPhase?: number;
+  borderLineCap?: LineCapStyle;
+  blendMode?: BlendMode;
+}
+
+export interface PDFPageDrawSVGElementOptions {
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  fontSize?: number;
+  fonts?: { [fontName: string]: PDFFont };
+}

package/src/api/StandardFonts.ts

@@ -0,0 +1,16 @@
+export enum StandardFonts {
+  Courier = 'Courier',
+  CourierBold = 'Courier-Bold',
+  CourierOblique = 'Courier-Oblique',
+  CourierBoldOblique = 'Courier-BoldOblique',
+  Helvetica = 'Helvetica',
+  HelveticaBold = 'Helvetica-Bold',
+  HelveticaOblique = 'Helvetica-Oblique',
+  HelveticaBoldOblique = 'Helvetica-BoldOblique',
+  TimesRoman = 'Times-Roman',
+  TimesRomanBold = 'Times-Bold',
+  TimesRomanItalic = 'Times-Italic',
+  TimesRomanBoldItalic = 'Times-BoldItalic',
+  Symbol = 'Symbol',
+  ZapfDingbats = 'ZapfDingbats',
+}

package/src/api/colors.ts

@@ -0,0 +1,109 @@
+import {
+  setFillingCmykColor,
+  setFillingGrayscaleColor,
+  setFillingRgbColor,
+  setStrokingCmykColor,
+  setStrokingGrayscaleColor,
+  setStrokingRgbColor,
+} from './operators';
+import { assertRange, assertIs, error } from '../utils';
+import ColorParser from 'color';
+
+export enum ColorTypes {
+  Grayscale = 'Grayscale',
+  RGB = 'RGB',
+  CMYK = 'CMYK',
+}
+
+export interface Grayscale {
+  type: ColorTypes.Grayscale;
+  gray: number;
+}
+
+export interface RGB {
+  type: ColorTypes.RGB;
+  red: number;
+  green: number;
+  blue: number;
+}
+
+export interface CMYK {
+  type: ColorTypes.CMYK;
+  cyan: number;
+  magenta: number;
+  yellow: number;
+  key: number;
+}
+
+export type Color = Grayscale | RGB | CMYK;
+
+export const grayscale = (gray: number): Grayscale => {
+  assertRange(gray, 'gray', 0.0, 1.0);
+  return { type: ColorTypes.Grayscale, gray };
+};
+
+export const rgb = (red: number, green: number, blue: number): RGB => {
+  assertRange(red, 'red', 0, 1);
+  assertRange(green, 'green', 0, 1);
+  assertRange(blue, 'blue', 0, 1);
+  return { type: ColorTypes.RGB, red, green, blue };
+};
+
+export const cmyk = (cyan: number, magenta: number, yellow: number, key: number): CMYK => {
+  assertRange(cyan, 'cyan', 0, 1);
+  assertRange(magenta, 'magenta', 0, 1);
+  assertRange(yellow, 'yellow', 0, 1);
+  assertRange(key, 'key', 0, 1);
+  return { type: ColorTypes.CMYK, cyan, magenta, yellow, key };
+};
+
+export const colorString = (color: string): { rgb: Color; alpha?: number } => {
+  assertIs(color, 'color', ['string']);
+  const colorDescription = ColorParser(color).unitObject();
+  return {
+    rgb: rgb(colorDescription.r, colorDescription.g, colorDescription.b),
+    alpha: colorDescription.alpha,
+  };
+};
+
+const { Grayscale, RGB, CMYK } = ColorTypes;
+
+// prettier-ignore
+export const setFillingColor = (color: Color) => 
+    color.type === Grayscale ? setFillingGrayscaleColor(color.gray)
+  : color.type === RGB       ? setFillingRgbColor(color.red, color.green, color.blue)
+  : color.type === CMYK      ? setFillingCmykColor(color.cyan, color.magenta, color.yellow, color.key)
+  : error(`Invalid color: ${JSON.stringify(color)}`);
+
+// prettier-ignore
+export const setStrokingColor = (color: Color) => 
+    color.type === Grayscale ? setStrokingGrayscaleColor(color.gray)
+  : color.type === RGB       ? setStrokingRgbColor(color.red, color.green, color.blue)
+  : color.type === CMYK      ? setStrokingCmykColor(color.cyan, color.magenta, color.yellow, color.key)
+  : error(`Invalid color: ${JSON.stringify(color)}`);
+
+// prettier-ignore
+export const componentsToColor = (comps?: number[], scale = 1) => (
+    comps?.length === 1 ? grayscale(
+      comps[0] * scale,
+    )
+  : comps?.length === 3 ? rgb(
+      comps[0] * scale, 
+      comps[1] * scale, 
+      comps[2] * scale,
+    )
+  : comps?.length === 4 ? cmyk(
+      comps[0] * scale, 
+      comps[1] * scale, 
+      comps[2] * scale, 
+      comps[3] * scale,
+    )
+  : undefined
+);
+
+// prettier-ignore
+export const colorToComponents = (color: Color) =>
+    color.type === Grayscale ? [color.gray]
+  : color.type === RGB       ? [color.red, color.green, color.blue]
+  : color.type === CMYK      ? [color.cyan, color.magenta, color.yellow, color.key]
+  : error(`Invalid color: ${JSON.stringify(color)}`);

package/src/api/errors.ts

@@ -0,0 +1,110 @@
+// tslint:disable: max-classes-per-file
+
+// TODO: Include link to documentation with example
+export class EncryptedPDFError extends Error {
+  constructor() {
+    const msg =
+      'Input document to `PDFDocument.load` is encrypted. You can use `PDFDocument.load(..., { ignoreEncryption: true })` if you wish to load the document anyways.';
+    super(msg);
+  }
+}
+
+// TODO: Include link to documentation with example
+export class FontkitNotRegisteredError extends Error {
+  constructor() {
+    const msg =
+      'Input to `PDFDocument.embedFont` was a custom font, but no `fontkit` instance was found. You must register a `fontkit` instance with `PDFDocument.registerFontkit(...)` before embedding custom fonts.';
+    super(msg);
+  }
+}
+
+// TODO: Include link to documentation with example
+export class ForeignPageError extends Error {
+  constructor() {
+    const msg =
+      'A `page` passed to `PDFDocument.addPage` or `PDFDocument.insertPage` was from a different (foreign) PDF document. If you want to copy pages from one PDFDocument to another, you must use `PDFDocument.copyPages(...)` to copy the pages before adding or inserting them.';
+    super(msg);
+  }
+}
+
+// TODO: Include link to documentation with example
+export class RemovePageFromEmptyDocumentError extends Error {
+  constructor() {
+    const msg = 'PDFDocument has no pages so `PDFDocument.removePage` cannot be called';
+    super(msg);
+  }
+}
+
+export class NoSuchFieldError extends Error {
+  constructor(name: string) {
+    const msg = `PDFDocument has no form field with the name "${name}"`;
+    super(msg);
+  }
+}
+
+export class UnexpectedFieldTypeError extends Error {
+  constructor(name: string, expected: any, actual: any) {
+    const expectedType = expected?.name;
+    const actualType = actual?.constructor?.name ?? actual;
+    const msg =
+      `Expected field "${name}" to be of type ${expectedType}, ` +
+      `but it is actually of type ${actualType}`;
+    super(msg);
+  }
+}
+
+export class MissingOnValueCheckError extends Error {
+  constructor(onValue: any) {
+    const msg = `Failed to select check box due to missing onValue: "${onValue}"`;
+    super(msg);
+  }
+}
+
+export class FieldAlreadyExistsError extends Error {
+  constructor(name: string) {
+    const msg = `A field already exists with the specified name: "${name}"`;
+    super(msg);
+  }
+}
+
+export class InvalidFieldNamePartError extends Error {
+  constructor(namePart: string) {
+    const msg = `Field name contains invalid component: "${namePart}"`;
+    super(msg);
+  }
+}
+
+export class FieldExistsAsNonTerminalError extends Error {
+  constructor(name: string) {
+    const msg = `A non-terminal field already exists with the specified name: "${name}"`;
+    super(msg);
+  }
+}
+
+export class RichTextFieldReadError extends Error {
+  constructor(fieldName: string) {
+    const msg = `Reading rich text fields is not supported: Attempted to read rich text field: ${fieldName}`;
+    super(msg);
+  }
+}
+
+export class CombedTextLayoutError extends Error {
+  constructor(lineLength: number, cellCount: number) {
+    const msg = `Failed to layout combed text as lineLength=${lineLength} is greater than cellCount=${cellCount}`;
+    super(msg);
+  }
+}
+
+export class ExceededMaxLengthError extends Error {
+  constructor(textLength: number, maxLength: number, name: string) {
+    const msg = `Attempted to set text with length=${textLength} for TextField with maxLength=${maxLength} and name=${name}`;
+    super(msg);
+  }
+}
+
+export class InvalidMaxLengthError extends Error {
+  constructor(textLength: number, maxLength: number, name: string) {
+    const msg = `Attempted to set maxLength=${maxLength}, which is less than ${textLength}, the length of this field's current value (name=${name})`;
+    super(msg);
+  }
+}

package/src/api/form/PDFButton.ts

@@ -0,0 +1,242 @@
+import PDFDocument from '../PDFDocument';
+import PDFPage from '../PDFPage';
+import PDFFont from '../PDFFont';
+import PDFImage from '../PDFImage';
+import { ImageAlignment } from '../image/alignment';
+import {
+  AppearanceProviderFor,
+  normalizeAppearance,
+  defaultButtonAppearanceProvider,
+} from './appearances';
+import PDFField, { FieldAppearanceOptions, assertFieldAppearanceOptions } from './PDFField';
+import { rgb } from '../colors';
+import { degrees } from '../rotations';
+
+import { PDFRef, PDFStream, PDFAcroPushButton, PDFWidgetAnnotation } from '../../core';
+import { assertIs, assertOrUndefined, assertPositive } from '../../utils';
+
+/**
+ * Represents a button field of a [[PDFForm]].
+ *
+ * [[PDFButton]] fields are interactive controls that users can click with their
+ * mouse. This type of [[PDFField]] is not stateful. The purpose of a button
+ * is to perform an action when the user clicks on it, such as opening a print
+ * modal or resetting the form. Buttons are typically rectangular in shape and
+ * have a text label describing the action that they perform when clicked.
+ */
+export default class PDFButton extends PDFField {
+  /**
+   * > **NOTE:** You probably don't want to call this method directly. Instead,
+   * > consider using the [[PDFForm.getButton]] method, which will create an
+   * > instance of [[PDFButton]] for you.
+   *
+   * Create an instance of [[PDFButton]] from an existing acroPushButton and ref
+   *
+   * @param acroPushButton The underlying `PDFAcroPushButton` for this button.
+   * @param ref The unique reference for this button.
+   * @param doc The document to which this button will belong.
+   */
+  static of = (acroPushButton: PDFAcroPushButton, ref: PDFRef, doc: PDFDocument) =>
+    new PDFButton(acroPushButton, ref, doc);
+
+  /** The low-level PDFAcroPushButton wrapped by this button. */
+  readonly acroField: PDFAcroPushButton;
+
+  private constructor(acroPushButton: PDFAcroPushButton, ref: PDFRef, doc: PDFDocument) {
+    super(acroPushButton, ref, doc);
+
+    assertIs(acroPushButton, 'acroButton', [[PDFAcroPushButton, 'PDFAcroPushButton']]);
+
+    this.acroField = acroPushButton;
+  }
+
+  /**
+   * Display an image inside the bounds of this button's widgets. For example:
+   * ```js
+   * const pngImage = await pdfDoc.embedPng(...)
+   * const button = form.getButton('some.button.field')
+   * button.setImage(pngImage, ImageAlignment.Center)
+   * ```
+   * This will update the appearances streams for each of this button's widgets.
+   * @param image The image that should be displayed.
+   * @param alignment The alignment of the image.
+   */
+  setImage(image: PDFImage, alignment = ImageAlignment.Center) {
+    const widgets = this.acroField.getWidgets();
+    for (let idx = 0, len = widgets.length; idx < len; idx++) {
+      const widget = widgets[idx];
+      const streamRef = this.createImageAppearanceStream(widget, image, alignment);
+      this.updateWidgetAppearances(widget, { normal: streamRef });
+    }
+
+    this.markAsClean();
+  }
+
+  /**
+   * Set the font size for this field. Larger font sizes will result in larger
+   * text being displayed when PDF readers render this button. Font sizes may
+   * be integer or floating point numbers. Supplying a negative font size will
+   * cause this method to throw an error.
+   *
+   * For example:
+   * ```js
+   * const button = form.getButton('some.button.field')
+   * button.setFontSize(4)
+   * button.setFontSize(15.7)
+   * ```
+   *
+   * > This method depends upon the existence of a default appearance
+   * > (`/DA`) string. If this field does not have a default appearance string,
+   * > or that string does not contain a font size (via the `Tf` operator),
+   * > then this method will throw an error.
+   *
+   * @param fontSize The font size to be used when rendering text in this field.
+   */
+  setFontSize(fontSize: number) {
+    assertPositive(fontSize, 'fontSize');
+    this.acroField.setFontSize(fontSize);
+    this.markAsDirty();
+  }
+
+  /**
+   * Show this button on the specified page with the given text. For example:
+   * ```js
+   * const ubuntuFont = await pdfDoc.embedFont(ubuntuFontBytes)
+   * const page = pdfDoc.addPage()
+   *
+   * const form = pdfDoc.getForm()
+   * const button = form.createButton('some.button.field')
+   *
+   * button.addToPage('Do Stuff', page, {
+   *   x: 50,
+   *   y: 75,
+   *   width: 200,
+   *   height: 100,
+   *   textColor: rgb(1, 0, 0),
+   *   backgroundColor: rgb(0, 1, 0),
+   *   borderColor: rgb(0, 0, 1),
+   *   borderWidth: 2,
+   *   rotate: degrees(90),
+   *   font: ubuntuFont,
+   * })
+   * ```
+   * This will create a new widget for this button field.
+   * @param text The text to be displayed for this button widget.
+   * @param page The page to which this button widget should be added.
+   * @param options The options to be used when adding this button widget.
+   */
+  addToPage(
+    // TODO: This needs to be optional, e.g. for image buttons
+    text: string,
+    page: PDFPage,
+    options?: FieldAppearanceOptions,
+  ) {
+    assertOrUndefined(text, 'text', ['string']);
+    assertOrUndefined(page, 'page', [[PDFPage, 'PDFPage']]);
+    assertFieldAppearanceOptions(options);
+
+    // Create a widget for this button
+    const widget = this.createWidget({
+      x: (options?.x ?? 0) - (options?.borderWidth ?? 0) / 2,
+      y: (options?.y ?? 0) - (options?.borderWidth ?? 0) / 2,
+      width: options?.width ?? 100,
+      height: options?.height ?? 50,
+      textColor: options?.textColor ?? rgb(0, 0, 0),
+      backgroundColor: options?.backgroundColor ?? rgb(0.75, 0.75, 0.75),
+      borderColor: options?.borderColor,
+      borderWidth: options?.borderWidth ?? 0,
+      rotate: options?.rotate ?? degrees(0),
+      caption: text,
+      hidden: options?.hidden,
+      page: page.ref,
+    });
+    const widgetRef = this.doc.context.register(widget.dict);
+
+    // Add widget to this field
+    this.acroField.addWidget(widgetRef);
+
+    // Set appearance streams for widget
+    const font = options?.font ?? this.doc.getForm().getDefaultFont();
+    this.updateWidgetAppearance(widget, font);
+
+    // Add widget to the given page
+    page.node.addAnnot(widgetRef);
+  }
+
+  /**
+   * Returns `true` if this button has been marked as dirty, or if any of this
+   * button's widgets do not have an appearance stream. For example:
+   * ```js
+   * const button = form.getButton('some.button.field')
+   * if (button.needsAppearancesUpdate()) console.log('Needs update')
+   * ```
+   * @returns Whether or not this button needs an appearance update.
+   */
+  needsAppearancesUpdate(): boolean {
+    if (this.isDirty()) return true;
+
+    const widgets = this.acroField.getWidgets();
+    for (let idx = 0, len = widgets.length; idx < len; idx++) {
+      const widget = widgets[idx];
+      const hasAppearances = widget.getAppearances()?.normal instanceof PDFStream;
+      if (!hasAppearances) return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Update the appearance streams for each of this button's widgets using
+   * the default appearance provider for buttons. For example:
+   * ```js
+   * const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica)
+   * const button = form.getButton('some.button.field')
+   * button.defaultUpdateAppearances(helvetica)
+   * ```
+   * @param font The font to be used for creating the appearance streams.
+   */
+  defaultUpdateAppearances(font: PDFFont) {
+    assertIs(font, 'font', [[PDFFont, 'PDFFont']]);
+    this.updateAppearances(font);
+  }
+
+  /**
+   * Update the appearance streams for each of this button's widgets using
+   * the given appearance provider. If no `provider` is passed, the default
+   * appearance provider for buttons will be used. For example:
+   * ```js
+   * const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica)
+   * const button = form.getButton('some.button.field')
+   * button.updateAppearances(helvetica, (field, widget, font) => {
+   *   ...
+   *   return {
+   *     normal: drawButton(...),
+   *     down: drawButton(...),
+   *   }
+   * })
+   * ```
+   * @param font The font to be used for creating the appearance streams.
+   * @param provider Optionally, the appearance provider to be used for
+   *                 generating the contents of the appearance streams.
+   */
+  updateAppearances(font: PDFFont, provider?: AppearanceProviderFor<PDFButton>) {
+    assertIs(font, 'font', [[PDFFont, 'PDFFont']]);
+    assertOrUndefined(provider, 'provider', [Function]);
+
+    const widgets = this.acroField.getWidgets();
+    for (let idx = 0, len = widgets.length; idx < len; idx++) {
+      const widget = widgets[idx];
+      this.updateWidgetAppearance(widget, font, provider);
+    }
+  }
+
+  private updateWidgetAppearance(
+    widget: PDFWidgetAnnotation,
+    font: PDFFont,
+    provider?: AppearanceProviderFor<PDFButton>,
+  ) {
+    const apProvider = provider ?? defaultButtonAppearanceProvider;
+    const appearances = normalizeAppearance(apProvider(this, widget, font));
+    this.updateWidgetAppearanceWithFont(widget, font, appearances);
+  }
+}