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

package/dist/api/PDFPageOptions.d.ts

@@ -0,0 +1,172 @@
+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 declare 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;
+    };
+}
+export {};

package/dist/api/StandardFonts.d.ts

@@ -0,0 +1,16 @@
+export declare 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/dist/api/colors.d.ts

@@ -0,0 +1,34 @@
+export declare 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 declare const grayscale: (gray: number) => Grayscale;
+export declare const rgb: (red: number, green: number, blue: number) => RGB;
+export declare const cmyk: (cyan: number, magenta: number, yellow: number, key: number) => CMYK;
+export declare const colorString: (color: string) => {
+    rgb: Color;
+    alpha?: number;
+};
+export declare const setFillingColor: (color: Color) => import("..").PDFOperator;
+export declare const setStrokingColor: (color: Color) => import("..").PDFOperator;
+export declare const componentsToColor: (comps?: number[], scale?: number) => Grayscale | RGB | CMYK | undefined;
+export declare const colorToComponents: (color: Color) => number[];

package/dist/api/errors.d.ts

@@ -0,0 +1,42 @@
+export declare class EncryptedPDFError extends Error {
+    constructor();
+}
+export declare class FontkitNotRegisteredError extends Error {
+    constructor();
+}
+export declare class ForeignPageError extends Error {
+    constructor();
+}
+export declare class RemovePageFromEmptyDocumentError extends Error {
+    constructor();
+}
+export declare class NoSuchFieldError extends Error {
+    constructor(name: string);
+}
+export declare class UnexpectedFieldTypeError extends Error {
+    constructor(name: string, expected: any, actual: any);
+}
+export declare class MissingOnValueCheckError extends Error {
+    constructor(onValue: any);
+}
+export declare class FieldAlreadyExistsError extends Error {
+    constructor(name: string);
+}
+export declare class InvalidFieldNamePartError extends Error {
+    constructor(namePart: string);
+}
+export declare class FieldExistsAsNonTerminalError extends Error {
+    constructor(name: string);
+}
+export declare class RichTextFieldReadError extends Error {
+    constructor(fieldName: string);
+}
+export declare class CombedTextLayoutError extends Error {
+    constructor(lineLength: number, cellCount: number);
+}
+export declare class ExceededMaxLengthError extends Error {
+    constructor(textLength: number, maxLength: number, name: string);
+}
+export declare class InvalidMaxLengthError extends Error {
+    constructor(textLength: number, maxLength: number, name: string);
+}

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

@@ -0,0 +1,137 @@
+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;
+}

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

@@ -0,0 +1,142 @@
+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;
+}