@adnsistemas/pdf-lib 1.18.0

package/src/core/acroform/utils.ts

@@ -0,0 +1,135 @@
+import PDFObject from 'src/core/objects/PDFObject';
+import PDFNumber from 'src/core/objects/PDFNumber';
+import PDFDict from 'src/core/objects/PDFDict';
+import PDFName from 'src/core/objects/PDFName';
+import PDFArray from 'src/core/objects/PDFArray';
+import PDFRef from 'src/core/objects/PDFRef';
+
+import PDFAcroField from 'src/core/acroform/PDFAcroField';
+import PDFAcroTerminal from 'src/core/acroform/PDFAcroTerminal';
+import PDFAcroNonTerminal from 'src/core/acroform/PDFAcroNonTerminal';
+import PDFAcroButton from 'src/core/acroform/PDFAcroButton';
+import PDFAcroSignature from 'src/core/acroform/PDFAcroSignature';
+import PDFAcroChoice from 'src/core/acroform/PDFAcroChoice';
+import PDFAcroText from 'src/core/acroform/PDFAcroText';
+import PDFAcroPushButton from 'src/core/acroform/PDFAcroPushButton';
+import PDFAcroRadioButton from 'src/core/acroform/PDFAcroRadioButton';
+import PDFAcroCheckBox from 'src/core/acroform/PDFAcroCheckBox';
+import PDFAcroComboBox from 'src/core/acroform/PDFAcroComboBox';
+import PDFAcroListBox from 'src/core/acroform/PDFAcroListBox';
+import { AcroButtonFlags, AcroChoiceFlags } from 'src/core/acroform/flags';
+
+export const createPDFAcroFields = (
+  kidDicts?: PDFArray,
+): [PDFAcroField, PDFRef][] => {
+  if (!kidDicts) return [];
+
+  const kids: [PDFAcroField, PDFRef][] = [];
+  for (let idx = 0, len = kidDicts.size(); idx < len; idx++) {
+    const ref = kidDicts.get(idx);
+    const dict = kidDicts.lookup(idx);
+    // if (dict instanceof PDFDict) kids.push(PDFAcroField.fromDict(dict));
+    if (ref instanceof PDFRef && dict instanceof PDFDict) {
+      kids.push([createPDFAcroField(dict, ref), ref]);
+    }
+  }
+
+  return kids;
+};
+
+export const createPDFAcroField = (
+  dict: PDFDict,
+  ref: PDFRef,
+): PDFAcroField => {
+  const isNonTerminal = isNonTerminalAcroField(dict);
+  if (isNonTerminal) return PDFAcroNonTerminal.fromDict(dict, ref);
+  return createPDFAcroTerminal(dict, ref);
+};
+
+// TODO: Maybe just check if the dict is *not* a widget? That might be better.
+
+// According to the PDF spec:
+//
+//   > A field's children in the hierarchy may also include widget annotations
+//   > that define its appearance on the page. A field that has children that
+//   > are fields is called a non-terminal field. A field that does not have
+//   > children that are fields is called a terminal field.
+//
+// The spec is not entirely clear about how to determine whether a given
+// dictionary represents an acrofield or a widget annotation. So we will assume
+// that a dictionary is an acrofield if it is a member of the `/Kids` array
+// and it contains a `/T` entry (widgets do not have `/T` entries). This isn't
+// a bullet proof solution, because the `/T` entry is technically defined as
+// optional for acrofields by the PDF spec. But in practice all acrofields seem
+// to have a `/T` entry defined.
+const isNonTerminalAcroField = (dict: PDFDict): boolean => {
+  const kids = dict.lookup(PDFName.of('Kids'));
+
+  if (kids instanceof PDFArray) {
+    for (let idx = 0, len = kids.size(); idx < len; idx++) {
+      const kid = kids.lookup(idx);
+      const kidIsField = kid instanceof PDFDict && kid.has(PDFName.of('T'));
+      if (kidIsField) return true;
+    }
+  }
+
+  return false;
+};
+
+const createPDFAcroTerminal = (dict: PDFDict, ref: PDFRef): PDFAcroTerminal => {
+  const ftNameOrRef = getInheritableAttribute(dict, PDFName.of('FT'));
+  const type = dict.context.lookup(ftNameOrRef, PDFName);
+
+  if (type === PDFName.of('Btn')) return createPDFAcroButton(dict, ref);
+  if (type === PDFName.of('Ch')) return createPDFAcroChoice(dict, ref);
+  if (type === PDFName.of('Tx')) return PDFAcroText.fromDict(dict, ref);
+  if (type === PDFName.of('Sig')) return PDFAcroSignature.fromDict(dict, ref);
+
+  // We should never reach this line. But there are a lot of weird PDFs out
+  // there. So, just to be safe, we'll try to handle things gracefully instead
+  // of throwing an error.
+  return PDFAcroTerminal.fromDict(dict, ref);
+};
+
+const createPDFAcroButton = (dict: PDFDict, ref: PDFRef): PDFAcroButton => {
+  const ffNumberOrRef = getInheritableAttribute(dict, PDFName.of('Ff'));
+  const ffNumber = dict.context.lookupMaybe(ffNumberOrRef, PDFNumber);
+  const flags = ffNumber?.asNumber() ?? 0;
+
+  if (flagIsSet(flags, AcroButtonFlags.PushButton)) {
+    return PDFAcroPushButton.fromDict(dict, ref);
+  } else if (flagIsSet(flags, AcroButtonFlags.Radio)) {
+    return PDFAcroRadioButton.fromDict(dict, ref);
+  } else {
+    return PDFAcroCheckBox.fromDict(dict, ref);
+  }
+};
+
+const createPDFAcroChoice = (dict: PDFDict, ref: PDFRef): PDFAcroChoice => {
+  const ffNumberOrRef = getInheritableAttribute(dict, PDFName.of('Ff'));
+  const ffNumber = dict.context.lookupMaybe(ffNumberOrRef, PDFNumber);
+  const flags = ffNumber?.asNumber() ?? 0;
+
+  if (flagIsSet(flags, AcroChoiceFlags.Combo)) {
+    return PDFAcroComboBox.fromDict(dict, ref);
+  } else {
+    return PDFAcroListBox.fromDict(dict, ref);
+  }
+};
+
+const flagIsSet = (flags: number, flag: number): boolean =>
+  (flags & flag) !== 0;
+
+const getInheritableAttribute = (startNode: PDFDict, name: PDFName) => {
+  let attribute: PDFObject | undefined;
+  ascend(startNode, (node) => {
+    if (!attribute) attribute = node.get(name);
+  });
+  return attribute;
+};
+
+const ascend = (startNode: PDFDict, visitor: (node: PDFDict) => any) => {
+  visitor(startNode);
+  const Parent = startNode.lookupMaybe(PDFName.of('Parent'), PDFDict);
+  if (Parent) ascend(Parent, visitor);
+};

package/src/core/annotation/AppearanceCharacteristics.ts

@@ -0,0 +1,133 @@
+import PDFDict from 'src/core/objects/PDFDict';
+import PDFName from 'src/core/objects/PDFName';
+import PDFNumber from 'src/core/objects/PDFNumber';
+import PDFArray from 'src/core/objects/PDFArray';
+import PDFHexString from 'src/core/objects/PDFHexString';
+import PDFString from 'src/core/objects/PDFString';
+
+class AppearanceCharacteristics {
+  readonly dict: PDFDict;
+
+  static fromDict = (dict: PDFDict): AppearanceCharacteristics =>
+    new AppearanceCharacteristics(dict);
+
+  protected constructor(dict: PDFDict) {
+    this.dict = dict;
+  }
+
+  R(): PDFNumber | undefined {
+    const R = this.dict.lookup(PDFName.of('R'));
+    if (R instanceof PDFNumber) return R;
+    return undefined;
+  }
+
+  BC(): PDFArray | undefined {
+    const BC = this.dict.lookup(PDFName.of('BC'));
+    if (BC instanceof PDFArray) return BC;
+    return undefined;
+  }
+
+  BG(): PDFArray | undefined {
+    const BG = this.dict.lookup(PDFName.of('BG'));
+    if (BG instanceof PDFArray) return BG;
+    return undefined;
+  }
+
+  CA(): PDFHexString | PDFString | undefined {
+    const CA = this.dict.lookup(PDFName.of('CA'));
+    if (CA instanceof PDFHexString || CA instanceof PDFString) return CA;
+    return undefined;
+  }
+
+  RC(): PDFHexString | PDFString | undefined {
+    const RC = this.dict.lookup(PDFName.of('RC'));
+    if (RC instanceof PDFHexString || RC instanceof PDFString) return RC;
+    return undefined;
+  }
+
+  AC(): PDFHexString | PDFString | undefined {
+    const AC = this.dict.lookup(PDFName.of('AC'));
+    if (AC instanceof PDFHexString || AC instanceof PDFString) return AC;
+    return undefined;
+  }
+
+  getRotation(): number | undefined {
+    return this.R()?.asNumber();
+  }
+
+  getBorderColor(): number[] | undefined {
+    const BC = this.BC();
+
+    if (!BC) return undefined;
+
+    const components: number[] = [];
+    for (let idx = 0, len = BC?.size(); idx < len; idx++) {
+      const component = BC.get(idx);
+      if (component instanceof PDFNumber) components.push(component.asNumber());
+    }
+
+    return components;
+  }
+
+  getBackgroundColor(): number[] | undefined {
+    const BG = this.BG();
+
+    if (!BG) return undefined;
+
+    const components: number[] = [];
+    for (let idx = 0, len = BG?.size(); idx < len; idx++) {
+      const component = BG.get(idx);
+      if (component instanceof PDFNumber) components.push(component.asNumber());
+    }
+
+    return components;
+  }
+
+  getCaptions(): { normal?: string; rollover?: string; down?: string } {
+    const CA = this.CA();
+    const RC = this.RC();
+    const AC = this.AC();
+
+    return {
+      normal: CA?.decodeText(),
+      rollover: RC?.decodeText(),
+      down: AC?.decodeText(),
+    };
+  }
+
+  setRotation(rotation: number) {
+    const R = this.dict.context.obj(rotation);
+    this.dict.set(PDFName.of('R'), R);
+  }
+
+  setBorderColor(color: number[]) {
+    const BC = this.dict.context.obj(color);
+    this.dict.set(PDFName.of('BC'), BC);
+  }
+
+  setBackgroundColor(color: number[]) {
+    const BG = this.dict.context.obj(color);
+    this.dict.set(PDFName.of('BG'), BG);
+  }
+
+  setCaptions(captions: { normal: string; rollover?: string; down?: string }) {
+    const CA = PDFHexString.fromText(captions.normal);
+    this.dict.set(PDFName.of('CA'), CA);
+
+    if (captions.rollover) {
+      const RC = PDFHexString.fromText(captions.rollover);
+      this.dict.set(PDFName.of('RC'), RC);
+    } else {
+      this.dict.delete(PDFName.of('RC'));
+    }
+
+    if (captions.down) {
+      const AC = PDFHexString.fromText(captions.down);
+      this.dict.set(PDFName.of('AC'), AC);
+    } else {
+      this.dict.delete(PDFName.of('AC'));
+    }
+  }
+}
+
+export default AppearanceCharacteristics;

package/src/core/annotation/BorderStyle.ts

@@ -0,0 +1,31 @@
+import PDFDict from 'src/core/objects/PDFDict';
+import PDFName from 'src/core/objects/PDFName';
+import PDFNumber from 'src/core/objects/PDFNumber';
+
+// TODO: Also handle the `/S` and `/D` entries
+class BorderStyle {
+  readonly dict: PDFDict;
+
+  static fromDict = (dict: PDFDict): BorderStyle => new BorderStyle(dict);
+
+  protected constructor(dict: PDFDict) {
+    this.dict = dict;
+  }
+
+  W(): PDFNumber | undefined {
+    const W = this.dict.lookup(PDFName.of('W'));
+    if (W instanceof PDFNumber) return W;
+    return undefined;
+  }
+
+  getWidth(): number | undefined {
+    return this.W()?.asNumber() ?? 1;
+  }
+
+  setWidth(width: number) {
+    const W = this.dict.context.obj(width);
+    this.dict.set(PDFName.of('W'), W);
+  }
+}
+
+export default BorderStyle;

package/src/core/annotation/PDFAnnotation.ts

@@ -0,0 +1,148 @@
+import PDFDict from 'src/core/objects/PDFDict';
+import PDFName from 'src/core/objects/PDFName';
+import PDFStream from 'src/core/objects/PDFStream';
+import PDFArray from 'src/core/objects/PDFArray';
+import PDFRef from 'src/core/objects/PDFRef';
+import PDFNumber from 'src/core/objects/PDFNumber';
+
+class PDFAnnotation {
+  readonly dict: PDFDict;
+
+  static fromDict = (dict: PDFDict): PDFAnnotation => new PDFAnnotation(dict);
+
+  protected constructor(dict: PDFDict) {
+    this.dict = dict;
+  }
+
+  // This is technically required by the PDF spec
+  Rect(): PDFArray | undefined {
+    return this.dict.lookup(PDFName.of('Rect'), PDFArray);
+  }
+
+  AP(): PDFDict | undefined {
+    return this.dict.lookupMaybe(PDFName.of('AP'), PDFDict);
+  }
+
+  F(): PDFNumber | undefined {
+    const numberOrRef = this.dict.lookup(PDFName.of('F'));
+    return this.dict.context.lookupMaybe(numberOrRef, PDFNumber);
+  }
+
+  getRectangle(): { x: number; y: number; width: number; height: number } {
+    const Rect = this.Rect();
+    return Rect?.asRectangle() ?? { x: 0, y: 0, width: 0, height: 0 };
+  }
+
+  setRectangle(rect: { x: number; y: number; width: number; height: number }) {
+    const { x, y, width, height } = rect;
+    const Rect = this.dict.context.obj([x, y, x + width, y + height]);
+    this.dict.set(PDFName.of('Rect'), Rect);
+  }
+
+  getAppearanceState(): PDFName | undefined {
+    const AS = this.dict.lookup(PDFName.of('AS'));
+    if (AS instanceof PDFName) return AS;
+    return undefined;
+  }
+
+  setAppearanceState(state: PDFName) {
+    this.dict.set(PDFName.of('AS'), state);
+  }
+
+  setAppearances(appearances: PDFDict) {
+    this.dict.set(PDFName.of('AP'), appearances);
+  }
+
+  ensureAP(): PDFDict {
+    let AP = this.AP();
+    if (!AP) {
+      AP = this.dict.context.obj({});
+      this.dict.set(PDFName.of('AP'), AP);
+    }
+    return AP;
+  }
+
+  getNormalAppearance(): PDFRef | PDFDict {
+    const AP = this.ensureAP();
+    const N = AP.get(PDFName.of('N'));
+    if (N instanceof PDFRef || N instanceof PDFDict) return N;
+
+    throw new Error(`Unexpected N type: ${N?.constructor.name}`);
+  }
+
+  /** @param appearance A PDFDict or PDFStream (direct or ref) */
+  setNormalAppearance(appearance: PDFRef | PDFDict) {
+    const AP = this.ensureAP();
+    AP.set(PDFName.of('N'), appearance);
+  }
+
+  /** @param appearance A PDFDict or PDFStream (direct or ref) */
+  setRolloverAppearance(appearance: PDFRef | PDFDict) {
+    const AP = this.ensureAP();
+    AP.set(PDFName.of('R'), appearance);
+  }
+
+  /** @param appearance A PDFDict or PDFStream (direct or ref) */
+  setDownAppearance(appearance: PDFRef | PDFDict) {
+    const AP = this.ensureAP();
+    AP.set(PDFName.of('D'), appearance);
+  }
+
+  removeRolloverAppearance() {
+    const AP = this.AP();
+    AP?.delete(PDFName.of('R'));
+  }
+
+  removeDownAppearance() {
+    const AP = this.AP();
+    AP?.delete(PDFName.of('D'));
+  }
+
+  getAppearances():
+    | {
+        normal: PDFStream | PDFDict;
+        rollover?: PDFStream | PDFDict;
+        down?: PDFStream | PDFDict;
+      }
+    | undefined {
+    const AP = this.AP();
+
+    if (!AP) return undefined;
+
+    const N = AP.lookup(PDFName.of('N'), PDFDict, PDFStream);
+    const R = AP.lookupMaybe(PDFName.of('R'), PDFDict, PDFStream);
+    const D = AP.lookupMaybe(PDFName.of('D'), PDFDict, PDFStream);
+
+    return { normal: N, rollover: R, down: D };
+  }
+
+  getFlags(): number {
+    return this.F()?.asNumber() ?? 0;
+  }
+
+  setFlags(flags: number) {
+    this.dict.set(PDFName.of('F'), PDFNumber.of(flags));
+  }
+
+  hasFlag(flag: number): boolean {
+    const flags = this.getFlags();
+    return (flags & flag) !== 0;
+  }
+
+  setFlag(flag: number) {
+    const flags = this.getFlags();
+    this.setFlags(flags | flag);
+  }
+
+  clearFlag(flag: number) {
+    const flags = this.getFlags();
+    this.setFlags(flags & ~flag);
+  }
+
+  setFlagTo(flag: number, enable: boolean) {
+    if (enable) this.setFlag(flag);
+    else this.clearFlag(flag);
+  }
+}
+
+export default PDFAnnotation;

package/src/core/annotation/PDFWidgetAnnotation.ts

@@ -0,0 +1,112 @@
+import PDFDict from 'src/core/objects/PDFDict';
+import PDFName from 'src/core/objects/PDFName';
+import PDFRef from 'src/core/objects/PDFRef';
+import PDFString from 'src/core/objects/PDFString';
+import PDFHexString from 'src/core/objects/PDFHexString';
+import PDFContext from 'src/core/PDFContext';
+import BorderStyle from 'src/core/annotation/BorderStyle';
+import PDFAnnotation from 'src/core/annotation/PDFAnnotation';
+import AppearanceCharacteristics from 'src/core/annotation/AppearanceCharacteristics';
+
+class PDFWidgetAnnotation extends PDFAnnotation {
+  static fromDict = (dict: PDFDict): PDFWidgetAnnotation =>
+    new PDFWidgetAnnotation(dict);
+
+  static create = (context: PDFContext, parent: PDFRef) => {
+    const dict = context.obj({
+      Type: 'Annot',
+      Subtype: 'Widget',
+      Rect: [0, 0, 0, 0],
+      Parent: parent,
+    });
+    return new PDFWidgetAnnotation(dict);
+  };
+
+  MK(): PDFDict | undefined {
+    const MK = this.dict.lookup(PDFName.of('MK'));
+    if (MK instanceof PDFDict) return MK;
+    return undefined;
+  }
+
+  BS(): PDFDict | undefined {
+    const BS = this.dict.lookup(PDFName.of('BS'));
+    if (BS instanceof PDFDict) return BS;
+    return undefined;
+  }
+
+  DA(): PDFString | PDFHexString | undefined {
+    const da = this.dict.lookup(PDFName.of('DA'));
+    if (da instanceof PDFString || da instanceof PDFHexString) return da;
+    return undefined;
+  }
+
+  P(): PDFRef | undefined {
+    const P = this.dict.get(PDFName.of('P'));
+    if (P instanceof PDFRef) return P;
+    return undefined;
+  }
+
+  setP(page: PDFRef) {
+    this.dict.set(PDFName.of('P'), page);
+  }
+
+  setDefaultAppearance(appearance: string) {
+    this.dict.set(PDFName.of('DA'), PDFString.of(appearance));
+  }
+
+  getDefaultAppearance(): string | undefined {
+    const DA = this.DA();
+
+    if (DA instanceof PDFHexString) {
+      return DA.decodeText();
+    }
+
+    return DA?.asString();
+  }
+
+  getAppearanceCharacteristics(): AppearanceCharacteristics | undefined {
+    const MK = this.MK();
+    if (MK) return AppearanceCharacteristics.fromDict(MK);
+    return undefined;
+  }
+
+  getOrCreateAppearanceCharacteristics(): AppearanceCharacteristics {
+    const MK = this.MK();
+    if (MK) return AppearanceCharacteristics.fromDict(MK);
+
+    const ac = AppearanceCharacteristics.fromDict(this.dict.context.obj({}));
+    this.dict.set(PDFName.of('MK'), ac.dict);
+    return ac;
+  }
+
+  getBorderStyle(): BorderStyle | undefined {
+    const BS = this.BS();
+    if (BS) return BorderStyle.fromDict(BS);
+    return undefined;
+  }
+
+  getOrCreateBorderStyle(): BorderStyle {
+    const BS = this.BS();
+    if (BS) return BorderStyle.fromDict(BS);
+
+    const bs = BorderStyle.fromDict(this.dict.context.obj({}));
+    this.dict.set(PDFName.of('BS'), bs.dict);
+    return bs;
+  }
+
+  getOnValue(): PDFName | undefined {
+    const normal = this.getAppearances()?.normal;
+
+    if (normal instanceof PDFDict) {
+      const keys = normal.keys();
+      for (let idx = 0, len = keys.length; idx < len; idx++) {
+        const key = keys[idx];
+        if (key !== PDFName.of('Off')) return key;
+      }
+    }
+
+    return undefined;
+  }
+}
+
+export default PDFWidgetAnnotation;

package/src/core/annotation/flags.ts

@@ -0,0 +1,90 @@
+const flag = (bitIndex: number) => 1 << bitIndex;
+
+/** From PDF spec table 165 */
+export enum AnnotationFlags {
+  /**
+   * If set, do not display the annotation if it does not belong to one of the
+   * standard annotation types and no annotation handler is available. If clear,
+   * display such an unknown annotation using an appearance stream specified by
+   * its appearance dictionary, if any.
+   */
+  Invisible = flag(1 - 1),
+
+  /**
+   * If set, do not display or print the annotation or allow it to interact with
+   * the user, regardless of its annotation type or whether an annotation
+   * handler is available.
+   *
+   * In cases where screen space is limited, the ability to hide and show
+   * annotations selectively can be used in combination with appearance streams
+   * to display auxiliary pop-up information similar in function to online help
+   * systems.
+   */
+  Hidden = flag(2 - 1),
+
+  /**
+   * If set, print the annotation when the page is printed. If clear, never
+   * print the annotation, regardless of whether it is displayed on the screen.
+   *
+   * This can be useful for annotations representing interactive pushbuttons,
+   * which would serve no meaningful purpose on the printed page.
+   */
+  Print = flag(3 - 1),
+
+  /**
+   * If set, do not scale the annotation’s appearance to match the magnification
+   * of the page. The location of the annotation on the page (defined by the
+   * upper-left corner of its annotation rectangle) shall remain fixed,
+   * regardless of the page magnification.
+   */
+  NoZoom = flag(4 - 1),
+
+  /**
+   * If set, do not rotate the annotation’s appearance to match the rotation of
+   * the page. The upper-left corner of the annotation rectangle shall remain in
+   * a fixed location on the page, regardless of the page rotation.
+   */
+  NoRotate = flag(5 - 1),
+
+  /**
+   * If set, do not display the annotation on the screen or allow it to interact
+   * with the user. The annotation may be printed (depending on the setting of
+   * the Print flag) but should be considered hidden for purposes of on-screen
+   * display and user interaction.
+   */
+  NoView = flag(6 - 1),
+
+  /**
+   * If set, do not allow the annotation to interact with the user. The
+   * annotation may be displayed or printed (depending on the settings of the
+   * NoView and Print flags) but should not respond to mouse clicks or change
+   * its appearance in response to mouse motions.
+   *
+   * This flag shall be ignored for widget annotations; its function is
+   * subsumed by the ReadOnly flag of the associated form field.
+   */
+  ReadOnly = flag(7 - 1),
+
+  /**
+   * If set, do not allow the annotation to be deleted or its properties
+   * (including position and size) to be modified by the user. However, this
+   * flag does not restrict changes to the annotation’s contents, such as the
+   * value of a form field.
+   */
+  Locked = flag(8 - 1),
+
+  /**
+   * If set, invert the interpretation of the NoView flag for certain events.
+   *
+   * A typical use is to have an annotation that appears only when a mouse
+   * cursor is held over it.
+   */
+  ToggleNoView = flag(9 - 1),
+
+  /**
+   * If set, do not allow the contents of the annotation to be modified by the
+   * user. This flag does not restrict deletion of the annotation or changes to
+   * other annotation properties, such as position and size.
+   */
+  LockedContents = flag(10 - 1),
+}

package/src/core/annotation/index.ts

@@ -0,0 +1,4 @@
+export { default as PDFAnnotation } from 'src/core/annotation/PDFAnnotation';
+export { default as PDFWidgetAnnotation } from 'src/core/annotation/PDFWidgetAnnotation';
+export { default as AppearanceCharacteristics } from 'src/core/annotation/AppearanceCharacteristics';
+export * from 'src/core/annotation/flags';