@pdfme/pdf-lib 6.0.3 → 6.0.4-dev.1

package/src/api/form/PDFRadioGroup.ts

@@ -1,455 +0,0 @@
-import PDFDocument from '../PDFDocument';
-import PDFPage from '../PDFPage';
-import PDFField, { FieldAppearanceOptions, assertFieldAppearanceOptions } from './PDFField';
-import {
-  AppearanceProviderFor,
-  normalizeAppearance,
-  defaultRadioGroupAppearanceProvider,
-} from './appearances';
-import { rgb } from '../colors';
-import { degrees } from '../rotations';
-
-import {
-  PDFName,
-  PDFRef,
-  PDFHexString,
-  PDFDict,
-  PDFWidgetAnnotation,
-  PDFAcroRadioButton,
-  AcroButtonFlags,
-} from '../../core';
-import { assertIs, assertOrUndefined, assertIsOneOf } from '../../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 = 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 = 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

@@ -1,44 +0,0 @@
-import PDFDocument from '../PDFDocument';
-import PDFField from './PDFField';
-
-import { PDFRef, PDFAcroSignature } from '../../core';
-import { assertIs } from '../../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;
-  }
-}