@adnsistemas/pdf-lib 1.18.0

package/src/api/form/PDFRadioGroup.ts

@@ -0,0 +1,471 @@
+import PDFDocument from 'src/api/PDFDocument';
+import PDFPage from 'src/api/PDFPage';
+import PDFField, {
+  FieldAppearanceOptions,
+  assertFieldAppearanceOptions,
+} from 'src/api/form/PDFField';
+import {
+  AppearanceProviderFor,
+  normalizeAppearance,
+  defaultRadioGroupAppearanceProvider,
+} from 'src/api/form/appearances';
+import { rgb } from 'src/api/colors';
+import { degrees } from 'src/api/rotations';
+
+import {
+  PDFName,
+  PDFRef,
+  PDFHexString,
+  PDFDict,
+  PDFWidgetAnnotation,
+  PDFAcroRadioButton,
+  AcroButtonFlags,
+} from 'src/core';
+import { assertIs, assertOrUndefined, assertIsOneOf } from 'src/utils';
+
+/**
+ * Represents a radio group field of a [[PDFForm]].
+ *
+ * [[PDFRadioGroup]] fields are collections of radio buttons. The purpose of a
+ * radio group is to enable users to select one option from a set of mutually
+ * exclusive choices. Each choice in a radio group is represented by a radio
+ * button. Radio buttons each have two states: `on` and `off`. At most one
+ * radio button in a group may be in the `on` state at any time. Users can
+ * click on a radio button to select it (and thereby automatically deselect any
+ * other radio button that might have already been selected). Some radio
+ * groups allow users to toggle a selected radio button `off` by clicking on
+ * it (see [[PDFRadioGroup.isOffToggleable]]).
+ *
+ * Note that some radio groups allow multiple radio buttons to be in the `on`
+ * state at the same type **if** they represent the same underlying value (see
+ * [[PDFRadioGroup.isMutuallyExclusive]]).
+ */
+export default class PDFRadioGroup extends PDFField {
+  /**
+   * > **NOTE:** You probably don't want to call this method directly. Instead,
+   * > consider using the [[PDFForm.getOptionList]] method, which will create an
+   * > instance of [[PDFOptionList]] for you.
+   *
+   * Create an instance of [[PDFOptionList]] from an existing acroRadioButton
+   * and ref
+   *
+   * @param acroRadioButton The underlying `PDFAcroRadioButton` for this
+   *                        radio group.
+   * @param ref The unique reference for this radio group.
+   * @param doc The document to which this radio group will belong.
+   */
+  static of = (
+    acroRadioButton: PDFAcroRadioButton,
+    ref: PDFRef,
+    doc: PDFDocument,
+  ) => new PDFRadioGroup(acroRadioButton, ref, doc);
+
+  /** The low-level PDFAcroRadioButton wrapped by this radio group. */
+  readonly acroField: PDFAcroRadioButton;
+
+  private constructor(
+    acroRadioButton: PDFAcroRadioButton,
+    ref: PDFRef,
+    doc: PDFDocument,
+  ) {
+    super(acroRadioButton, ref, doc);
+
+    assertIs(acroRadioButton, 'acroRadioButton', [
+      [PDFAcroRadioButton, 'PDFAcroRadioButton'],
+    ]);
+
+    this.acroField = acroRadioButton;
+  }
+
+  /**
+   * Get the list of available options for this radio group. Each option is
+   * represented by a radio button. These radio buttons are displayed at
+   * various locations in the document, potentially on different pages (though
+   * typically they are stacked horizontally or vertically on the same page).
+   * For example:
+   * ```js
+   * const radioGroup = form.getRadioGroup('some.radioGroup.field')
+   * const options = radioGroup.getOptions()
+   * console.log('Radio Group options:', options)
+   * ```
+   * @returns The options for this radio group.
+   */
+  getOptions(): string[] {
+    const exportValues = this.acroField.getExportValues();
+    if (exportValues) {
+      const exportOptions = new Array<string>(exportValues.length);
+      for (let idx = 0, len = exportValues.length; idx < len; idx++) {
+        exportOptions[idx] = exportValues[idx].decodeText();
+      }
+      return exportOptions;
+    }
+
+    const onValues = this.acroField.getOnValues();
+    const onOptions = new Array<string>(onValues.length);
+    for (let idx = 0, len = onOptions.length; idx < len; idx++) {
+      onOptions[idx] = onValues[idx].decodeText();
+    }
+    return onOptions;
+  }
+
+  /**
+   * Get the selected option for this radio group. The selected option is
+   * represented by the radio button in this group that is turned on. At most
+   * one radio button in a group can be selected. If no buttons in this group
+   * are selected, `undefined` is returned.
+   * For example:
+   * ```js
+   * const radioGroup = form.getRadioGroup('some.radioGroup.field')
+   * const selected = radioGroup.getSelected()
+   * console.log('Selected radio button:', selected)
+   * ```
+   * @returns The selected option for this radio group.
+   */
+  getSelected(): string | undefined {
+    const value = this.acroField.getValue();
+    if (value === PDFName.of('Off')) return undefined;
+    const exportValues = this.acroField.getExportValues();
+    if (exportValues) {
+      const onValues = this.acroField.getOnValues();
+      for (let idx = 0, len = onValues.length; idx < len; idx++) {
+        if (onValues[idx] === value) return exportValues[idx].decodeText();
+      }
+    }
+    return value.decodeText();
+  }
+
+  // // TODO: Figure out why this seems to crash Acrobat. Maybe it's because we
+  // //       aren't removing the widget reference from the page's Annots?
+  // removeOption(option: string) {
+  //   assertIs(option, 'option', ['string']);
+  //   // TODO: Assert is valid `option`!
+
+  //   const onValues = this.acroField.getOnValues();
+  //   const exportValues = this.acroField.getExportValues();
+  //   if (exportValues) {
+  //     for (let idx = 0, len = exportValues.length; idx < len; idx++) {
+  //       if (exportValues[idx].decodeText() === option) {
+  //         this.acroField.removeWidget(idx);
+  //         this.acroField.removeExportValue(idx);
+  //       }
+  //     }
+  //   } else {
+  //     for (let idx = 0, len = onValues.length; idx < len; idx++) {
+  //       const value = onValues[idx];
+  //       if (value.decodeText() === option) {
+  //         this.acroField.removeWidget(idx);
+  //         this.acroField.removeExportValue(idx);
+  //       }
+  //     }
+  //   }
+  // }
+
+  /**
+   * Select an option for this radio group. This operation is analogous to a
+   * human user clicking one of the radio buttons in this group via a PDF
+   * reader to toggle it on. This method will update the underlying state of
+   * the radio group to indicate which option has been selected. PDF libraries
+   * and readers will be able to extract this value from the saved document and
+   * determine which option was selected.
+   *
+   * For example:
+   * ```js
+   * const radioGroup = form.getRadioGroup('best.superhero.radioGroup')
+   * radioGroup.select('One Punch Man')
+   * ```
+   *
+   * This method will mark this radio group as dirty, causing its appearance
+   * streams to be updated when either [[PDFDocument.save]] or
+   * [[PDFForm.updateFieldAppearances]] is called. The updated appearance
+   * streams will display a dot inside the widget of this check box field
+   * that represents the selected option.
+   *
+   * @param option The option to be selected.
+   */
+  select(option: string) {
+    assertIs(option, 'option', ['string']);
+
+    const validOptions = this.getOptions();
+    assertIsOneOf(option, 'option', validOptions);
+
+    this.markAsDirty();
+
+    const onValues = this.acroField.getOnValues();
+    const exportValues = this.acroField.getExportValues();
+    if (exportValues) {
+      for (let idx = 0, len = exportValues.length; idx < len; idx++) {
+        if (exportValues[idx].decodeText() === option) {
+          this.acroField.setValue(onValues[idx]);
+        }
+      }
+    } else {
+      for (let idx = 0, len = onValues.length; idx < len; idx++) {
+        const value = onValues[idx];
+        if (value.decodeText() === option) this.acroField.setValue(value);
+      }
+    }
+  }
+
+  /**
+   * Clear any selected option for this dropdown. This will result in all
+   * radio buttons in this group being toggled off. This method will update
+   * the underlying state of the dropdown to indicate that no radio buttons
+   * have been selected.
+   * For example:
+   * ```js
+   * const radioGroup = form.getRadioGroup('some.radioGroup.field')
+   * radioGroup.clear()
+   * ```
+   * This method will mark this radio group as dirty. See
+   * [[PDFRadioGroup.select]] for more details about what this means.
+   */
+  clear() {
+    this.markAsDirty();
+    this.acroField.setValue(PDFName.of('Off'));
+  }
+
+  /**
+   * Returns `true` if users can click on radio buttons in this group to toggle
+   * them off. The alternative is that once a user clicks on a radio button
+   * to select it, the only way to deselect it is by selecting on another radio
+   * button in the group. See [[PDFRadioGroup.enableOffToggling]] and
+   * [[PDFRadioGroup.disableOffToggling]]. For example:
+   * ```js
+   * const radioGroup = form.getRadioGroup('some.radioGroup.field')
+   * if (radioGroup.isOffToggleable()) console.log('Off toggling is enabled')
+   * ```
+   */
+  isOffToggleable() {
+    return !this.acroField.hasFlag(AcroButtonFlags.NoToggleToOff);
+  }
+
+  /**
+   * Allow users to click on selected radio buttons in this group to toggle
+   * them off. For example:
+   * ```js
+   * const radioGroup = form.getRadioGroup('some.radioGroup.field')
+   * radioGroup.enableOffToggling()
+   * ```
+   * > **NOTE:** This feature is documented in the PDF specification
+   * > (Table 226). However, most PDF readers do not respect this option and
+   * > prevent users from toggling radio buttons off even when it is enabled.
+   * > At the time of this writing (9/6/2020) Mac's Preview software did
+   * > respect the option. Adobe Acrobat, Foxit Reader, and Google Chrome did
+   * > not.
+   */
+  enableOffToggling() {
+    this.acroField.setFlagTo(AcroButtonFlags.NoToggleToOff, false);
+  }
+
+  /**
+   * Prevent users from clicking on selected radio buttons in this group to
+   * toggle them off. Clicking on a selected radio button will have no effect.
+   * The only way to deselect a selected radio button is to click on a
+   * different radio button in the group. For example:
+   * ```js
+   * const radioGroup = form.getRadioGroup('some.radioGroup.field')
+   * radioGroup.disableOffToggling()
+   * ```
+   */
+  disableOffToggling() {
+    this.acroField.setFlagTo(AcroButtonFlags.NoToggleToOff, true);
+  }
+
+  /**
+   * Returns `true` if the radio buttons in this group are mutually exclusive.
+   * This means that when the user selects a radio button, only that specific
+   * button will be turned on. Even if other radio buttons in the group
+   * represent the same value, they will not be enabled. The alternative to
+   * this is that clicking a radio button will select that button along with
+   * any other radio buttons in the group that share the same value. See
+   * [[PDFRadioGroup.enableMutualExclusion]] and
+   * [[PDFRadioGroup.disableMutualExclusion]].
+   * For example:
+   * ```js
+   * const radioGroup = form.getRadioGroup('some.radioGroup.field')
+   * if (radioGroup.isMutuallyExclusive()) console.log('Mutual exclusion is enabled')
+   * ```
+   */
+  isMutuallyExclusive() {
+    return !this.acroField.hasFlag(AcroButtonFlags.RadiosInUnison);
+  }
+
+  /**
+   * When the user clicks a radio button in this group it will be selected. In
+   * addition, any other radio buttons in this group that share the same
+   * underlying value will also be selected. For example:
+   * ```js
+   * const radioGroup = form.getRadioGroup('some.radioGroup.field')
+   * radioGroup.enableMutualExclusion()
+   * ```
+   * Note that this option must be enabled prior to adding options to the
+   * radio group. It does not currently apply retroactively to existing
+   * radio buttons in the group.
+   */
+  enableMutualExclusion() {
+    this.acroField.setFlagTo(AcroButtonFlags.RadiosInUnison, false);
+  }
+
+  /**
+   * When the user clicks a radio button in this group only it will be selected.
+   * No other radio buttons in the group will be selected, even if they share
+   * the same underlying value. For example:
+   * ```js
+   * const radioGroup = form.getRadioGroup('some.radioGroup.field')
+   * radioGroup.disableMutualExclusion()
+   * ```
+   * Note that this option must be disabled prior to adding options to the
+   * radio group. It does not currently apply retroactively to existing
+   * radio buttons in the group.
+   */
+  disableMutualExclusion() {
+    this.acroField.setFlagTo(AcroButtonFlags.RadiosInUnison, true);
+  }
+
+  /**
+   * Add a new radio button to this group on the specified page. For example:
+   * ```js
+   * const page = pdfDoc.addPage()
+   *
+   * const form = pdfDoc.getForm()
+   * const radioGroup = form.createRadioGroup('best.gundam')
+   *
+   * const options = {
+   *   x: 50,
+   *   width: 25,
+   *   height: 25,
+   *   textColor: rgb(1, 0, 0),
+   *   backgroundColor: rgb(0, 1, 0),
+   *   borderColor: rgb(0, 0, 1),
+   *   borderWidth: 2,
+   *   rotate: degrees(90),
+   * }
+   *
+   * radioGroup.addOptionToPage('Exia', page, { ...options, y: 50 })
+   * radioGroup.addOptionToPage('Dynames', page, { ...options, y: 110 })
+   * ```
+   * This will create a new radio button widget for this radio group field.
+   * @param option The option that the radio button widget represents.
+   * @param page The page to which the radio button widget should be added.
+   * @param options The options to be used when adding the radio button widget.
+   */
+  addOptionToPage(
+    option: string,
+    page: PDFPage,
+    options?: FieldAppearanceOptions,
+  ) {
+    assertIs(option, 'option', ['string']);
+    assertIs(page, 'page', [[PDFPage, 'PDFPage']]);
+    assertFieldAppearanceOptions(options);
+
+    // Create a widget for this radio button
+    const widget = this.createWidget({
+      x: options?.x ?? 0,
+      y: options?.y ?? 0,
+      width: options?.width ?? 50,
+      height: options?.height ?? 50,
+      textColor: options?.textColor ?? rgb(0, 0, 0),
+      backgroundColor: options?.backgroundColor ?? rgb(1, 1, 1),
+      borderColor: options?.borderColor ?? rgb(0, 0, 0),
+      borderWidth: options?.borderWidth ?? 1,
+      rotate: options?.rotate ?? degrees(0),
+      hidden: options?.hidden,
+      page: page.ref,
+    });
+    const widgetRef = this.doc.context.register(widget.dict);
+
+    // Add widget to this field
+    const apStateValue = this.acroField.addWidgetWithOpt(
+      widgetRef,
+      PDFHexString.fromText(option),
+      !this.isMutuallyExclusive(),
+    );
+
+    // Set appearance streams for widget
+    widget.setAppearanceState(PDFName.of('Off'));
+    this.updateWidgetAppearance(widget, apStateValue);
+
+    // Add widget to the given page
+    page.node.addAnnot(widgetRef);
+  }
+
+  /**
+   * Returns `true` if any of this group's radio button widgets do not have an
+   * appearance stream for their current state. For example:
+   * ```js
+   * const radioGroup = form.getRadioGroup('some.radioGroup.field')
+   * if (radioGroup.needsAppearancesUpdate()) console.log('Needs update')
+   * ```
+   * @returns Whether or not this radio group needs an appearance update.
+   */
+  needsAppearancesUpdate(): boolean {
+    const widgets = this.acroField.getWidgets();
+    for (let idx = 0, len = widgets.length; idx < len; idx++) {
+      const widget = widgets[idx];
+      const state = widget.getAppearanceState();
+      const normal = widget.getAppearances()?.normal;
+
+      if (!(normal instanceof PDFDict)) return true;
+      if (state && !normal.has(state)) return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Update the appearance streams for each of this group's radio button widgets
+   * using the default appearance provider for radio groups. For example:
+   * ```js
+   * const radioGroup = form.getRadioGroup('some.radioGroup.field')
+   * radioGroup.defaultUpdateAppearances()
+   * ```
+   */
+  defaultUpdateAppearances() {
+    this.updateAppearances();
+  }
+
+  // rg.updateAppearances((field: any, widget: any) => {
+  //   assert(field === rg);
+  //   assert(widget instanceof PDFWidgetAnnotation);
+  //   return { on: [...rectangle, ...circle], off: [...rectangle, ...circle] };
+  // });
+
+  /**
+   * Update the appearance streams for each of this group's radio button widgets
+   * using the given appearance provider. If no `provider` is passed, the
+   * default appearance provider for radio groups will be used. For example:
+   * ```js
+   * const radioGroup = form.getRadioGroup('some.radioGroup.field')
+   * radioGroup.updateAppearances((field, widget) => {
+   *   ...
+   *   return {
+   *     normal: { on: drawRadioButton(...), off: drawRadioButton(...) },
+   *     down: { on: drawRadioButton(...), off: drawRadioButton(...) },
+   *   }
+   * })
+   * ```
+   * @param provider Optionally, the appearance provider to be used for
+   *                 generating the contents of the appearance streams.
+   */
+  updateAppearances(provider?: AppearanceProviderFor<PDFRadioGroup>) {
+    assertOrUndefined(provider, 'provider', [Function]);
+
+    const widgets = this.acroField.getWidgets();
+    for (let idx = 0, len = widgets.length; idx < len; idx++) {
+      const widget = widgets[idx];
+      const onValue = widget.getOnValue();
+      if (!onValue) continue;
+      this.updateWidgetAppearance(widget, onValue, provider);
+    }
+  }
+
+  private updateWidgetAppearance(
+    widget: PDFWidgetAnnotation,
+    onValue: PDFName,
+    provider?: AppearanceProviderFor<PDFRadioGroup>,
+  ) {
+    const apProvider = provider ?? defaultRadioGroupAppearanceProvider;
+    const appearances = normalizeAppearance(apProvider(this, widget));
+    this.updateOnOffWidgetAppearance(widget, onValue, appearances);
+  }
+}

package/src/api/form/PDFSignature.ts

@@ -0,0 +1,53 @@
+import PDFDocument from 'src/api/PDFDocument';
+import PDFField from 'src/api/form/PDFField';
+
+import { PDFRef, PDFAcroSignature } from 'src/core';
+import { assertIs } from 'src/utils';
+
+/**
+ * Represents a signature field of a [[PDFForm]].
+ *
+ * [[PDFSignature]] fields are digital signatures. `pdf-lib` does not
+ * currently provide any specialized APIs for creating digital signatures or
+ * reading the contents of existing digital signatures.
+ */
+export default class PDFSignature extends PDFField {
+  /**
+   * > **NOTE:** You probably don't want to call this method directly. Instead,
+   * > consider using the [[PDFForm.getSignature]] method, which will create an
+   * > instance of [[PDFSignature]] for you.
+   *
+   * Create an instance of [[PDFSignature]] from an existing acroSignature and
+   * ref
+   *
+   * @param acroSignature The underlying `PDFAcroSignature` for this signature.
+   * @param ref The unique reference for this signature.
+   * @param doc The document to which this signature will belong.
+   */
+  static of = (
+    acroSignature: PDFAcroSignature,
+    ref: PDFRef,
+    doc: PDFDocument,
+  ) => new PDFSignature(acroSignature, ref, doc);
+
+  /** The low-level PDFAcroSignature wrapped by this signature. */
+  readonly acroField: PDFAcroSignature;
+
+  private constructor(
+    acroSignature: PDFAcroSignature,
+    ref: PDFRef,
+    doc: PDFDocument,
+  ) {
+    super(acroSignature, ref, doc);
+
+    assertIs(acroSignature, 'acroSignature', [
+      [PDFAcroSignature, 'PDFAcroSignature'],
+    ]);
+
+    this.acroField = acroSignature;
+  }
+
+  needsAppearancesUpdate() {
+    return false;
+  }
+}