@syncfusion/ej2-pdf/src/pdf/core/pdf-merge.d.ts

Feature-rich JavaScript PDF library with built-in support for loading and manipulating PDF document.

import { PdfFont, PdfFontStyle } from './fonts/pdf-standard-font';
import { PdfField } from './form/field';
import { PdfForm } from './form/form';
import { _PdfCrossReference } from './pdf-cross-reference';
import { PdfDocument } from './pdf-document';
import { PdfBookmarkBase, PdfNamedDestination } from './pdf-outline';
import { PdfDestination, PdfPage } from './pdf-page';
import { PdfPageImportOptions } from './pdf-page-import-options';
import { _PdfDictionary, _PdfReference } from './pdf-primitives';
import { _PdfBaseStream } from './base-stream';
/**
 * Helper that merges/imports pages, annotations, form fields, layers, and bookmarks between PDF documents.
 *
 * @private
 */
export declare class _PdfMergeHelper {
    /**
     * Cache mapping pages to their bookmark nodes for efficient updates.
     *
     * @private
     */
    _bookmarkHashTable: Map<PdfPage, PdfBookmarkBase[]>;
    /**
     * Accumulator for named destinations to be written to the Names tree.
     *
     * @private
     */
    _namedDestinations: any[];
    /**
     * Accumulates bookmark nodes discovered during import.
     *
     * @private
     */
    _bookmarks: any[];
    /**
     * Temporary storage for imported form fields.
     *
     * @private
     */
    _fields: any[];
    /**
     * Mapping of source page dictionaries to destination page objects.
     *
     * @private
     */
    _pageReference: Map<_PdfDictionary, PdfPage>;
    /**
     * Mapping of source page references to destination page indexes for bookmark link fix-ups.
     *
     * @private
     */
    _bookmarksPageLinkReference: Map<_PdfReference, number>;
    /**
     * Collected destination arrays from annotations to be fixed after import.
     *
     * @private
     */
    _destination: any[];
    /**
     * Lookup of oldtonew references created during copy to reconcile layer references.
     *
     * @private
     */
    _newList: Map<_PdfReference, _PdfReference>;
    /**
     * Mapping of annotation index to its associated layer reference.
     *
     * @private
     */
    _annotationLayer: Map<number, _PdfReference>;
    /**
     * Indicates if optional content are present during import.
     *
     * @private
     */
    _isLayersPresent: boolean;
    /**
     * Tracks field names already present in destination to avoid duplicates.
     *
     * @private
     */
    _fieldNames: string[];
    /**
     * Destination document cross-reference table.
     *
     * @private
     */
    _crossReference: _PdfCrossReference;
    /**
     * Destination document receiving pages and objects.
     *
     * @private
     */
    _destinationDocument: PdfDocument;
    /**
     * Source document providing pages and objects to import.
     *
     * @private
     */
    _sourceDocument: PdfDocument;
    /**
     * Options that control how pages and related resources are imported.
     *
     * @private
     */
    _options: PdfPageImportOptions;
    /**
     * Temporary storage for widget/field kid references encountered during processing.
     *
     * @private
     */
    _kidsReference: any[];
    /**
     * Mapping of source field index to newly created parent field reference in the destination.
     *
     * @private
     */
    _formFieldsCollection: Map<number, _PdfReference>;
    /**
     * Collected field references that will be assigned to the destination AcroForm.
     *
     * @private
     */
    _formFields: _PdfReference[];
    /**
     * Indicates whether the current operation duplicates an existing page within the same document.
     *
     * @private
     */
    _isDuplicatePage: boolean;
    /**
     * Running count used when appending newly parsed fields into the destination form.
     *
     * @private
     */
    _fieldCount: number;
    /**
     * Helper responsible for copying dictionaries, streams, arrays, and references between xrefs.
     *
     * @private
     */
    _copier: _PdfCopier;
    constructor(crossReference: _PdfCrossReference, destination: PdfDocument, source: PdfDocument, pageReference: Map<_PdfDictionary, PdfPage>, options: PdfPageImportOptions);
    /**
     * Imports a page from the source document into the destination document, handling resources, annotations, form fields, and layers.
     *
     * @private
     * @param {PdfPage} page The source page to import.
     * @param {number} index The index at which the page should be inserted in the destination document.
     * @param {boolean} layers Indicates whether optional content should be merged.
     * @param {boolean} isCopiedPage Specifies whether the operation is duplicating an existing page.
     * @param {PdfPageImportOptions} [options] Optional import settings including rotation and optimization.
     * @param {boolean} [isSplitDocument] Indicates whether the operation is part of splitting a document.
     * @returns {void}
     */
    _importPages(page: PdfPage, index: number, layers: boolean, isCopiedPage: boolean, options?: PdfPageImportOptions, isSplitDocument?: boolean): void;
    /**
     * Imports annotations from a source page into a destination page, preserving destinations and optional content references.
     *
     * @private
     * @param {PdfPage} page The source page containing annotations.
     * @param {PdfPage} newPage The destination page to receive the copied annotations.
     * @returns {void}
     */
    _importAnnotation(page: PdfPage, newPage: PdfPage): void;
    /**
     * Groups and merges form fields for the imported page, aligning kids arrays and regenerating appearances when required.
     *
     * @private
     * @param {PdfForm} form The source form collection to analyze.
     * @param {PdfPage} oldPage The original page where the widgets reside.
     * @param {PdfPage} newPage The destination page where widgets will be grouped.
     * @returns {void}
     */
    _formFieldsGroupingSupport(form: PdfForm, oldPage: PdfPage, newPage: PdfPage): void;
    /**
     * Groups kids between source and destination fields, creating or updating widget dictionaries and appearances.
     *
     * @private
     * @param {PdfField} destinationField The destination field to receive kids.
     * @param {PdfField} field The source field providing kids.
     * @param {_PdfReference[]} kidsArray The source page annotations array.
     * @param {_PdfReference[]} destKids The kids array of the destination field to be updated.
     * @param {_PdfReference[]} oldKids The original kids from the source field.
     * @param {_PdfReference} ref The destination page reference to assign to widgets.
     * @param {_PdfReference[]} array The destination page annotations array to append to.
     * @param {number} [index] Optional index of the kid in the source field.
     * @param {number} [fieldIndex] Optional field index used for mapping.
     * @param {_PdfDictionary} [drEntry] Optional default resources dictionary for appearance generation.
     * @param {any} [widget] Optional widget information used for certain field types. // eslint-disable-line
     * @returns {_PdfReference[]} The updated annotations array with any new widget references.
     */
    _groupFormFieldsKids(destinationField: PdfField, field: PdfField, kidsArray: _PdfReference[], destKids: _PdfReference[], oldKids: _PdfReference[], ref: _PdfReference, array: _PdfReference[], index?: number, fieldIndex?: number, drEntry?: _PdfDictionary, widget?: any): _PdfReference[];
    /**
     * Creates or updates a destination parent field with kids and appends the appropriate widget dictionaries and references.
     *
     * @private
     * @param {PdfField} destinationField The destination field to update.
     * @param {PdfField} field The source field used to derive structure and widget data.
     * @param {_PdfDictionary} fieldDictionary The field dictionary used to build a new parent field.
     * @param {number} index The source kid index, or `null/undefined` when using a provided dictionary.
     * @param {number} fieldIndex The index of the form field in the global collection.
     * @param {_PdfReference} ref The destination page reference for widget placement.
     * @param {_PdfReference[]} oldKids The original kids from the source field.
     * @param {_PdfReference[]} array The annotations array to append new widget references to.
     * @param {_PdfDictionary} drEntry The default resources dictionary, for fonts and appearance resources.
     * @param {_PdfDictionary} [formFieldDictionary] Optional field dictionary when no kid index is selected.
     * @returns {void}
     */
    _updateFieldsWithKids(destinationField: PdfField, field: PdfField, fieldDictionary: _PdfDictionary, index: number, fieldIndex: number, ref: _PdfReference, oldKids: _PdfReference[], array: _PdfReference[], drEntry: _PdfDictionary, formFieldDictionary?: _PdfDictionary): void;
    /**
     * Removes the specified keys from a dictionary and returns the updated dictionary.
     *
     * @private
     * @param {_PdfDictionary} dictionary The dictionary to modify.
     * @param {string[]} keys The keys to remove from the dictionary.
     * @returns {_PdfDictionary} The updated dictionary without the specified keys.
     */
    _removeFieldDictionary(dictionary: _PdfDictionary, keys: string[]): _PdfDictionary;
    /**
     * Updates a field or widget dictionary with page and parent references and marks it as updated.
     *
     * @private
     * @param {_PdfDictionary} dictionary The dictionary to update.
     * @param {_PdfReference} pageRef The page reference where the widget resides.
     * @param {_PdfReference} parentRef The parent field reference to assign.
     * @returns {void}
     */
    _updateFieldDictionary(dictionary: _PdfDictionary, pageRef: _PdfReference, parentRef: _PdfReference): void;
    /**
     * Creates a new field dictionary by copying selected entries from an existing dictionary and removing them from the originals.
     *
     * @private
     * @param {_PdfDictionary} fieldDictionary The source field dictionary to copy from.
     * @param {_PdfDictionary} destDictionary The destination dictionary from which keys will also be removed.
     * @returns {_PdfDictionary} A new field dictionary to act as a parent.
     */
    _createNewFieldDictionary(fieldDictionary: _PdfDictionary, destDictionary: _PdfDictionary): _PdfDictionary;
    /**
     * Determines the style glyph or state used for checkbox/radio appearances based on MK dictionary or field type.
     *
     * @private
     * @param {any} item The widget item to assign style information to. // eslint-disable-line
     * @param {PdfField} field The associated field to infer default style when MK is not present.
     * @returns {void}
     */
    _getItemStyle(item: any, field: PdfField): void;
    /**
     * Creates appearance streams and templates for the destination field and its widgets using the provided DR resources.
     *
     * @private
     * @param {PdfField} destinationField The destination field to render appearance for.
     * @param {PdfField} field The source field guiding appearance characteristics.
     * @param {_PdfDictionary} oldDictionary The source widget dictionary.
     * @param {_PdfDictionary} dictionary The destination widget dictionary.
     * @param {_PdfDictionary} drEntry The default resources dictionary for font resolution.
     * @param {any} [widget] Optional widget context for signatures or list items. // eslint-disable-line
     * @returns {void}
     */
    _createAppearance(destinationField: PdfField, field: PdfField, oldDictionary: _PdfDictionary, dictionary: _PdfDictionary, drEntry: _PdfDictionary, widget?: any): void;
    /**
     * Resolves a PDF font for widget appearance from DS/DA entries and the form default resources dictionary.
     *
     * @private
     * @param {_PdfDictionary} item The annotation or widget dictionary that may contain DS/DA.
     * @param {_PdfDictionary} formDictionary The form default resources dictionary (DR) used to resolve fonts.
     * @returns {PdfFont} The resolved PDF font.
     */
    _obtainFont(item: _PdfDictionary, formDictionary: _PdfDictionary): PdfFont;
    /**
     * Resolves the font style (bold/italic/regular) from a base font name.
     *
     * @private
     * @param {string} fontStyle The base font name.
     * @returns {PdfFontStyle} The resolved style.
     */
    _getFontStyle(fontStyle: string): PdfFontStyle;
    /**
     * Imports form fields for a given page, creating widgets in the destination and merging form DR resources.
     *
     * @private
     * @param {PdfPage} page The source page that contains the fields.
     * @param {PdfForm} pdfForm The source form collection to read from.
     * @param {PdfPage} newPage The destination page to place the widgets on.
     * @returns {void}
     */
    _importFormField(page: PdfPage, pdfForm: PdfForm, newPage: PdfPage): void;
    /**
     * Inserts form fields and widgets for the given source field into the destination form and page annotations.
     *
     * @private
     * @param {number} index The index of the source field within the form.
     * @param {PdfField} pdfField The source field to insert.
     * @param {PdfForm} form The destination form collection.
     * @param {_PdfReference} ref The destination page reference to assign to widgets.
     * @param {_PdfReference[]} array The destination page annotations array to append to.
     * @param {_PdfReference[]} kidsArray The list of source widget references on the page for filtering.
     * @returns {_PdfReference[]} The updated annotations array with newly added widget references.
     */
    _insertFormFields(index: number, pdfField: PdfField, form: PdfForm, ref: _PdfReference, array: _PdfReference[], kidsArray: _PdfReference[]): _PdfReference[];
    /**
     * Merges the updated form fields collection into the destination document's AcroForm dictionary.
     *
     * @private
     * @returns {void}
     */
    _mergeFormFieldsWithDocument(): void;
    /**
     * Imports optional content (layers) properties into the destination document and merges default view settings.
     *
     * @private
     * @param {_PdfDictionary} ocProperties The source catalog dictionary that contains OCProperties.
     * @param {boolean} layers Indicates whether layers are present and should be merged.
     * @returns {void}
     */
    _importLayers(ocProperties: _PdfDictionary, layers: boolean): void;
    /**
     * Merges layer properties from the source page into the destination page including Properties, XObject, and annotations.
     *
     * @private
     * @param {_PdfDictionary} newPageDictionary The destination page dictionary.
     * @param {_PdfDictionary} oldPageDictionary The source page dictionary.
     * @param {_PdfCrossReference} crossReference The cross-reference used to dereference objects.
     * @returns {void}
     */
    _mergeLayer(newPageDictionary: _PdfDictionary, oldPageDictionary: _PdfDictionary, crossReference: _PdfCrossReference): void;
    /**
     * Exports collected bookmarks to the destination document, fixing page destinations and named destinations.
     *
     * @private
     * @param {PdfDocument} document The destination document to write bookmarks to.
     * @param {number} pageCount The number of pages considered during export.
     * @returns {void}
     */
    _exportBookmarks(document: PdfDocument, pageCount: number): void;
    /**
     * Creates a new named destination mapped to a new page based on an existing named destination.
     *
     * @private
     * @param {PdfNamedDestination} nDest The source named destination.
     * @param {PdfPage} page The destination page to associate with.
     * @returns {PdfNamedDestination} The cloned named destination with updated page reference.
     */
    _getNamedDestination(nDest: PdfNamedDestination, page: PdfPage): PdfNamedDestination;
    /**
     * Clones a destination for a different page while preserving mode, zoom, and location.
     *
     * @private
     * @param {PdfPage} page The new page for the destination.
     * @param {PdfDestination} dest The original destination to copy.
     * @returns {PdfDestination} The new destination that targets the given page.
     */
    _getDestination(page: PdfPage, dest: PdfDestination): PdfDestination;
    /**
     * Serializes a PDF object (primitive, array, dictionary, or reference) into a target container.
     *
     * @private
     * @param {PdfDocument} document The document being written to.
     * @param {_PdfDictionary} [table] The destination dictionary when writing key/value pairs.
     * @param {any} [value] The value to serialize. // eslint-disable-line
     * @param {_PdfDictionary} [dictionary] The current context dictionary used for dereferencing.
     * @param {string} [key] The key under which to store the value in the table.
     * @param {any[]} [array] The destination array when writing list entries. // eslint-disable-line
     * @param {_PdfReference} [ref] Optional reference handle for object mapping.
     * @returns {void}
     */
    _writeObject(document: PdfDocument, table?: _PdfDictionary, value?: any, dictionary?: _PdfDictionary, key?: string, array?: any[], ref?: _PdfReference): void;
    /**
     * Writes a key/value or list into a dictionary or array, managing reference remapping for layers.
     *
     * @private
     * @param {any} value The primitive value to write, if any. // eslint-disable-line
     * @param {_PdfDictionary} table The destination dictionary for key/value pairs.
     * @param {string} key The key name for dictionary insertion.
     * @param {any[]} array The destination array when writing list entries. // eslint-disable-line
     * @param {_PdfReference} ref The reference used to map or replace objects.
     * @param {any[]|_PdfDictionary} list The serialized list or sub-dictionary being written. // eslint-disable-line
     * @returns {void}
     */
    _writeDictionary(value: any, table: _PdfDictionary, key: string, array: any[], ref: _PdfReference, list: any[] | // eslint-disable-line
    _PdfDictionary): void;
    /**
     * Serializes an array of PDF objects into a destination list.
     *
     * @private
     * @param {PdfDocument} document The document being written to.
     * @param {any[]} array The destination list to receive serialized items. // eslint-disable-line
     * @param {any[]} value The source array to serialize. // eslint-disable-line
     * @param {_PdfDictionary} dictionary The context dictionary used for dereferencing.
     * @returns {void}
     */
    _writeArray(document: PdfDocument, array: any[], value: any[], dictionary: _PdfDictionary): void;
    /**
     * Writes all properties from a source dictionary into a destination dictionary, dereferencing references when needed.
     *
     * @private
     * @param {PdfDocument} document The document being written to.
     * @param {_PdfDictionary} table The destination dictionary to populate.
     * @param {_PdfDictionary} dictionary The source dictionary whose entries will be serialized.
     * @returns {void}
     */
    _writePropertiesDictionary(document: PdfDocument, table: _PdfDictionary, dictionary: _PdfDictionary): void;
    /**
     * Fixes stored destinations to point to the newly created page references after import.
     *
     * @private
     * @param {PdfDocument} document The destination document to resolve references against.
     * @returns {void}
     */
    _fixDestinations(document: PdfDocument): void;
    /**
     * Inserts a new page in the destination document mirroring size, boxes, margins, orientation, and rotation from the source.
     *
     * @private
     * @param {PdfPage} page The source page to mirror.
     * @param {number} [index] Optional insertion index.
     * @returns {PdfPage} The newly created destination page.
     */
    _insertNewPage(page: PdfPage, index?: number): PdfPage;
    /**
     * Disposes internal state and temporary collections used during import/merge operations.
     *
     * @private
     * @returns {void}
     */
    _objectDispose(): void;
}
/**
 * Provides low-level object copying helpers for PDF structures, including dictionaries, arrays, streams, and references.
 *
 * @private
 */
export declare class _PdfCopier {
    /**
     * Tracks source-to-destination reference mappings to avoid duplicate cloning.
     *
     * @private
     */
    _traversedObjects: Map<_PdfReference, _PdfReference>;
    /**
     * Cross-reference table of the target document where copied objects are stored.
     *
     * @private
     */
    _targetCrossReference: _PdfCrossReference;
    /**
     * Cross-reference table of the source document from which objects are fetched.
     *
     * @private
     */
    _sourceCrossReference: _PdfCrossReference;
    /**
     * Indicates whether grouping support is enabled during copy operations.
     *
     * @private
     */
    _isGroupingSupport: boolean;
    /**
     * Initializes a new copier with target and source cross reference tables.
     *
     * @private
     * @param {_PdfCrossReference} targetCrossReference The destination cross-reference table.
     * @param {_PdfCrossReference} sourceCrossReference The source cross-reference table.
     */
    constructor(targetCrossReference: _PdfCrossReference, sourceCrossReference: _PdfCrossReference);
    /**
     * Copies a PDF object depending on its type, returning a copied value or mapped reference.
     *
     * @private
     * @param {any} object The object to copy.
     * @returns {any} The copied object or target reference.
     */
    _copy(object: any): any;
    /**
     * Copies a dictionary and its entries, with optional handling for appearance dictionaries when copying pages.
     *
     * @private
     * @param {_PdfDictionary} element The dictionary to copy from the source cross reference.
     * @param {boolean} [copiedPage] Indicates whether the dictionary belongs to a page copy.
     * @returns {_PdfDictionary} The cloned dictionary in the target context.
     */
    _copyDictionary(element: _PdfDictionary, copiedPage?: boolean): _PdfDictionary;
    /**
     * Deep-copies an array by copying each element into the target context.
     *
     * @private
     * @param {any[]} originalArray The array to copy.
     * @returns {any[]} The copied array.
     */
    _copyArray(originalArray: any[]): any[];
    /**
     * Copies a base stream or content stream, preserving bytes and cloning its dictionary.
     *
     * @private
     * @param {_PdfBaseStream} originalStream The source stream to copy.
     * @returns {_PdfBaseStream} The cloned content stream in the target context.
     */
    _copyStream(originalStream: _PdfBaseStream): _PdfBaseStream;
    /**
     * Copies or reuses a reference, ensuring a consistent mapping from source to target references.
     *
     * @private
     * @param {_PdfReference} element The source reference to copy.
     * @returns {any} The new reference or copied value for non-container objects. // eslint-disable-line
     */
    _copyReference(element: _PdfReference): any;
    /**
     * Adds a copied object to the target cross reference and returns its newly created reference.
     *
     * @private
     * @param {any} element The dictionary or stream to add. // eslint-disable-line
     * @returns {_PdfReference} The new reference pointing to the added object.
     */
    _addToDestination(element: any): _PdfReference;
}