@adnsistemas/pdf-lib 1.18.0

package/es/api/form/PDFButton.d.ts

@@ -0,0 +1,138 @@
+import PDFDocument from "../PDFDocument";
+import PDFPage from "../PDFPage";
+import PDFFont from "../PDFFont";
+import PDFImage from "../PDFImage";
+import { ImageAlignment } from "../image/alignment";
+import { AppearanceProviderFor } from "./appearances";
+import PDFField, { FieldAppearanceOptions } from "./PDFField";
+import { PDFRef, PDFAcroPushButton } from "../../core";
+/**
+ * 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) => PDFButton;
+    /** The low-level PDFAcroPushButton wrapped by this button. */
+    readonly acroField: PDFAcroPushButton;
+    private constructor();
+    /**
+     * 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): void;
+    /**
+     * 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): void;
+    /**
+     * 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(text: string, page: PDFPage, options?: FieldAppearanceOptions): void;
+    /**
+     * 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;
+    /**
+     * 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): void;
+    /**
+     * 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>): void;
+    private updateWidgetAppearance;
+}
+//# sourceMappingURL=PDFButton.d.ts.map

package/es/api/form/PDFButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PDFButton.d.ts","sourceRoot":"","sources":["../../../src/api/form/PDFButton.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,uBAA4B;AAC9C,OAAO,OAAO,mBAAwB;AACtC,OAAO,OAAO,mBAAwB;AACtC,OAAO,QAAQ,oBAAyB;AACxC,OAAO,EAAE,cAAc,EAAE,2BAAgC;AACzD,OAAO,EACL,qBAAqB,EAGtB,sBAAiC;AAClC,OAAO,QAAQ,EAAE,EACf,sBAAsB,EAEvB,mBAA8B;AAI/B,OAAO,EACL,MAAM,EAEN,iBAAiB,EAElB,mBAAiB;AAGlB;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,OAAO,SAAU,SAAQ,QAAQ;IAC7C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,mBACS,iBAAiB,OAC5B,MAAM,OACN,WAAW,eAC2B;IAE7C,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAEtC,OAAO;IAcP;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,iBAAwB;IAe3D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM;IAM5B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,SAAS,CAEP,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,sBAAsB;IAkClC;;;;;;;;OAQG;IACH,sBAAsB,IAAI,OAAO;IAcjC;;;;;;;;;OASG;IACH,wBAAwB,CAAC,IAAI,EAAE,OAAO;IAKtC;;;;;;;;;;;;;;;;;;OAkBG;IACH,iBAAiB,CACf,IAAI,EAAE,OAAO,EACb,QAAQ,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC;IAY7C,OAAO,CAAC,sBAAsB;CAS/B"}

package/es/api/form/PDFButton.js

@@ -0,0 +1,218 @@
+import { __extends } from "tslib";
+import PDFPage from "../PDFPage";
+import PDFFont from "../PDFFont";
+import { ImageAlignment } from "../image/alignment";
+import { normalizeAppearance, defaultButtonAppearanceProvider, } from "./appearances";
+import PDFField, { assertFieldAppearanceOptions, } from "./PDFField";
+import { rgb } from "../colors";
+import { degrees } from "../rotations";
+import { PDFStream, PDFAcroPushButton, } 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.
+ */
+var PDFButton = /** @class */ (function (_super) {
+    __extends(PDFButton, _super);
+    function PDFButton(acroPushButton, ref, doc) {
+        var _this = _super.call(this, acroPushButton, ref, doc) || this;
+        assertIs(acroPushButton, 'acroButton', [
+            [PDFAcroPushButton, 'PDFAcroPushButton'],
+        ]);
+        _this.acroField = acroPushButton;
+        return _this;
+    }
+    /**
+     * 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.
+     */
+    PDFButton.prototype.setImage = function (image, alignment) {
+        if (alignment === void 0) { alignment = ImageAlignment.Center; }
+        var widgets = this.acroField.getWidgets();
+        for (var idx = 0, len = widgets.length; idx < len; idx++) {
+            var widget = widgets[idx];
+            var 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.
+     */
+    PDFButton.prototype.setFontSize = function (fontSize) {
+        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.
+     */
+    PDFButton.prototype.addToPage = function (
+    // TODO: This needs to be optional, e.g. for image buttons
+    text, page, options) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        assertOrUndefined(text, 'text', ['string']);
+        assertOrUndefined(page, 'page', [[PDFPage, 'PDFPage']]);
+        assertFieldAppearanceOptions(options);
+        // Create a widget for this button
+        var widget = this.createWidget({
+            x: ((_a = options === null || options === void 0 ? void 0 : options.x) !== null && _a !== void 0 ? _a : 0) - ((_b = options === null || options === void 0 ? void 0 : options.borderWidth) !== null && _b !== void 0 ? _b : 0) / 2,
+            y: ((_c = options === null || options === void 0 ? void 0 : options.y) !== null && _c !== void 0 ? _c : 0) - ((_d = options === null || options === void 0 ? void 0 : options.borderWidth) !== null && _d !== void 0 ? _d : 0) / 2,
+            width: (_e = options === null || options === void 0 ? void 0 : options.width) !== null && _e !== void 0 ? _e : 100,
+            height: (_f = options === null || options === void 0 ? void 0 : options.height) !== null && _f !== void 0 ? _f : 50,
+            textColor: (_g = options === null || options === void 0 ? void 0 : options.textColor) !== null && _g !== void 0 ? _g : rgb(0, 0, 0),
+            backgroundColor: (_h = options === null || options === void 0 ? void 0 : options.backgroundColor) !== null && _h !== void 0 ? _h : rgb(0.75, 0.75, 0.75),
+            borderColor: options === null || options === void 0 ? void 0 : options.borderColor,
+            borderWidth: (_j = options === null || options === void 0 ? void 0 : options.borderWidth) !== null && _j !== void 0 ? _j : 0,
+            rotate: (_k = options === null || options === void 0 ? void 0 : options.rotate) !== null && _k !== void 0 ? _k : degrees(0),
+            caption: text,
+            hidden: options === null || options === void 0 ? void 0 : options.hidden,
+            page: page.ref,
+        });
+        var widgetRef = this.doc.context.register(widget.dict);
+        // Add widget to this field
+        this.acroField.addWidget(widgetRef);
+        // Set appearance streams for widget
+        var font = (_l = options === null || options === void 0 ? void 0 : options.font) !== null && _l !== void 0 ? _l : 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.
+     */
+    PDFButton.prototype.needsAppearancesUpdate = function () {
+        var _a;
+        if (this.isDirty())
+            return true;
+        var widgets = this.acroField.getWidgets();
+        for (var idx = 0, len = widgets.length; idx < len; idx++) {
+            var widget = widgets[idx];
+            var hasAppearances = ((_a = widget.getAppearances()) === null || _a === void 0 ? void 0 : _a.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.
+     */
+    PDFButton.prototype.defaultUpdateAppearances = function (font) {
+        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.
+     */
+    PDFButton.prototype.updateAppearances = function (font, provider) {
+        assertIs(font, 'font', [[PDFFont, 'PDFFont']]);
+        assertOrUndefined(provider, 'provider', [Function]);
+        var widgets = this.acroField.getWidgets();
+        for (var idx = 0, len = widgets.length; idx < len; idx++) {
+            var widget = widgets[idx];
+            this.updateWidgetAppearance(widget, font, provider);
+        }
+    };
+    PDFButton.prototype.updateWidgetAppearance = function (widget, font, provider) {
+        var apProvider = provider !== null && provider !== void 0 ? provider : defaultButtonAppearanceProvider;
+        var appearances = normalizeAppearance(apProvider(this, widget, font));
+        this.updateWidgetAppearanceWithFont(widget, font, appearances);
+    };
+    /**
+     * > **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.
+     */
+    PDFButton.of = function (acroPushButton, ref, doc) { return new PDFButton(acroPushButton, ref, doc); };
+    return PDFButton;
+}(PDFField));
+export default PDFButton;
+//# sourceMappingURL=PDFButton.js.map

package/es/api/form/PDFButton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PDFButton.js","sourceRoot":"","sources":["../../../src/api/form/PDFButton.ts"],"names":[],"mappings":"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"}

package/es/api/form/PDFCheckBox.d.ts

@@ -0,0 +1,143 @@
+import PDFDocument from "../PDFDocument";
+import PDFPage from "../PDFPage";
+import { AppearanceProviderFor } from "./appearances";
+import PDFField, { FieldAppearanceOptions } from "./PDFField";
+import { PDFRef, PDFAcroCheckBox } from "../../core";
+/**
+ * Represents a check box field of a [[PDFForm]].
+ *
+ * [[PDFCheckBox]] fields are interactive boxes that users can click with their
+ * mouse. This type of [[PDFField]] has two states: `on` and `off`. The purpose
+ * of a check box is to enable users to select from one or more options, where
+ * each option is represented by a single check box. Check boxes are typically
+ * square in shape and display a check mark when they are in the `on` state.
+ */
+export default class PDFCheckBox extends PDFField {
+    /**
+     * > **NOTE:** You probably don't want to call this method directly. Instead,
+     * > consider using the [[PDFForm.getCheckBox]] method, which will create an
+     * > instance of [[PDFCheckBox]] for you.
+     *
+     * Create an instance of [[PDFCheckBox]] from an existing acroCheckBox and ref
+     *
+     * @param acroCheckBox The underlying `PDFAcroCheckBox` for this check box.
+     * @param ref The unique reference for this check box.
+     * @param doc The document to which this check box will belong.
+     */
+    static of: (acroCheckBox: PDFAcroCheckBox, ref: PDFRef, doc: PDFDocument) => PDFCheckBox;
+    /** The low-level PDFAcroCheckBox wrapped by this check box. */
+    readonly acroField: PDFAcroCheckBox;
+    private constructor();
+    /**
+     * Mark this check box. This operation is analogous to a human user clicking
+     * a check box to fill it in a PDF reader. This method will update the
+     * underlying state of the check box field to indicate it has been selected.
+     * PDF libraries and readers will be able to extract this value from the
+     * saved document and determine that it was selected.
+     *
+     * For example:
+     * ```js
+     * const checkBox = form.getCheckBox('some.checkBox.field')
+     * checkBox.check()
+     * ```
+     *
+     * This method will mark this check box 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 check mark inside the widgets of this check box
+     * field.
+     */
+    check(): void;
+    /**
+     * Clears this check box. This operation is analogous to a human user clicking
+     * a check box to unmark it in a PDF reader. This method will update the
+     * underlying state of the check box field to indicate it has been deselected.
+     * PDF libraries and readers will be able to extract this value from the
+     * saved document and determine that it was not selected.
+     *
+     * For example:
+     * ```js
+     * const checkBox = form.getCheckBox('some.checkBox.field')
+     * checkBox.uncheck()
+     * ```
+     *
+     * This method will mark this check box as dirty. See [[PDFCheckBox.check]]
+     * for more details about what this means.
+     */
+    uncheck(): void;
+    /**
+     * Returns `true` if this check box is selected (either by a human user via
+     * a PDF reader, or else programmatically via software). For example:
+     * ```js
+     * const checkBox = form.getCheckBox('some.checkBox.field')
+     * if (checkBox.isChecked()) console.log('check box is selected')
+     * ```
+     * @returns Whether or not this check box is selected.
+     */
+    isChecked(): boolean;
+    /**
+     * Show this check box on the specified page. For example:
+     * ```js
+     * const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica)
+     * const page = pdfDoc.addPage()
+     *
+     * const form = pdfDoc.getForm()
+     * const checkBox = form.createCheckBox('some.checkBox.field')
+     *
+     * checkBox.addToPage(page, {
+     *   x: 50,
+     *   y: 75,
+     *   width: 25,
+     *   height: 25,
+     *   textColor: rgb(1, 0, 0),
+     *   backgroundColor: rgb(0, 1, 0),
+     *   borderColor: rgb(0, 0, 1),
+     *   borderWidth: 2,
+     *   rotate: degrees(90),
+     * })
+     * ```
+     * This will create a new widget for this check box field.
+     * @param page The page to which this check box widget should be added.
+     * @param options The options to be used when adding this check box widget.
+     */
+    addToPage(page: PDFPage, options?: FieldAppearanceOptions): void;
+    /**
+     * Returns `true` if any of this check box's widgets do not have an
+     * appearance stream for its current state. For example:
+     * ```js
+     * const checkBox = form.getCheckBox('some.checkBox.field')
+     * if (checkBox.needsAppearancesUpdate()) console.log('Needs update')
+     * ```
+     * @returns Whether or not this check box needs an appearance update.
+     */
+    needsAppearancesUpdate(): boolean;
+    /**
+     * Update the appearance streams for each of this check box's widgets using
+     * the default appearance provider for check boxes. For example:
+     * ```js
+     * const checkBox = form.getCheckBox('some.checkBox.field')
+     * checkBox.defaultUpdateAppearances()
+     * ```
+     */
+    defaultUpdateAppearances(): void;
+    /**
+     * Update the appearance streams for each of this check box's widgets using
+     * the given appearance provider. If no `provider` is passed, the default
+     * appearance provider for check boxs will be used. For example:
+     * ```js
+     * const checkBox = form.getCheckBox('some.checkBox.field')
+     * checkBox.updateAppearances((field, widget) => {
+     *   ...
+     *   return {
+     *     normal: { on: drawCheckBox(...), off: drawCheckBox(...) },
+     *     down: { on: drawCheckBox(...), off: drawCheckBox(...) },
+     *   }
+     * })
+     * ```
+     * @param provider Optionally, the appearance provider to be used for
+     *                 generating the contents of the appearance streams.
+     */
+    updateAppearances(provider?: AppearanceProviderFor<PDFCheckBox>): void;
+    private updateWidgetAppearance;
+}
+//# sourceMappingURL=PDFCheckBox.d.ts.map

package/es/api/form/PDFCheckBox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PDFCheckBox.d.ts","sourceRoot":"","sources":["../../../src/api/form/PDFCheckBox.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,uBAA4B;AAC9C,OAAO,OAAO,mBAAwB;AACtC,OAAO,EACL,qBAAqB,EAGtB,sBAAiC;AAGlC,OAAO,QAAQ,EAAE,EACf,sBAAsB,EAEvB,mBAA8B;AAE/B,OAAO,EAEL,MAAM,EAEN,eAAe,EAEhB,mBAAiB;AAGlB;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,QAAQ;IAC/C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,iBAAkB,eAAe,OAAO,MAAM,OAAO,WAAW,iBAC/B;IAE1C,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IAEpC,OAAO;IAcP;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK;IAML;;;;;;;;;;;;;;;OAeG;IACH,OAAO;IAKP;;;;;;;;OAQG;IACH,SAAS,IAAI,OAAO;IAKpB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,sBAAsB;IAsCzD;;;;;;;;OAQG;IACH,sBAAsB,IAAI,OAAO;IAcjC;;;;;;;OAOG;IACH,wBAAwB;IAIxB;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC,WAAW,CAAC;IAa/D,OAAO,CAAC,sBAAsB;CAS/B"}