@cj-tech-master/excelts 9.1.0 → 9.2.0

package/dist/browser/modules/pdf/builder/form-appearance.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Form field appearance stream generation.
+ *
+ * Generates visual appearance streams for PDF form fields so that field
+ * values are visible in all PDF viewers — even those that do not honor
+ * the `/NeedAppearances` flag.
+ *
+ * @see PDF Reference 1.7, §12.5.5 — Appearance Streams
+ * @see PDF Reference 1.7, §12.7.4 — Field Appearance
+ */
+/** Options for generating a text field appearance stream. */
+export interface TextFieldAppearanceOptions {
+    /** The text value to display. */
+    value: string;
+    /** Widget annotation rectangle [x1, y1, x2, y2]. */
+    rect: number[];
+    /** Font size in points. 0 or omitted = auto-size to fit the field height. */
+    fontSize?: number;
+    /** Font resource name to reference (e.g. "Helv"). */
+    fontName?: string;
+    /** Text alignment within the field. */
+    alignment?: "left" | "center" | "right";
+}
+/**
+ * Generate an appearance stream for a text form field.
+ *
+ * Builds a minimal content stream that clips to the widget rect and
+ * draws the field value using the specified (or default) font.
+ *
+ * @returns The raw stream bytes and a resources dictionary string.
+ */
+export declare function generateTextFieldAppearance(options: TextFieldAppearanceOptions): {
+    stream: Uint8Array;
+    resources: string;
+};
+/**
+ * Generate appearance streams for a checkbox form field.
+ *
+ * Returns two streams:
+ * - `streamOn`:  draws a checkmark (✓-like shape) inside the rect
+ * - `streamOff`: empty appearance (blank field)
+ *
+ * @param checked - Whether to generate the checked or unchecked variant
+ *                  (both are always returned; `checked` is ignored — both
+ *                  on and off streams are produced).
+ * @param rect - Widget annotation rectangle [x1, y1, x2, y2].
+ */
+export declare function generateCheckboxAppearance(_checked: boolean, rect: number[]): {
+    streamOn: Uint8Array;
+    streamOff: Uint8Array;
+};
+/**
+ * Build the BBox array string for a form XObject appearance stream.
+ * The bounding box is in the widget's coordinate space: [0 0 width height].
+ */
+export declare function buildAppearanceBBox(rect: number[]): string;

package/dist/browser/modules/pdf/builder/form-appearance.js

@@ -0,0 +1,140 @@
+/**
+ * Form field appearance stream generation.
+ *
+ * Generates visual appearance streams for PDF form fields so that field
+ * values are visible in all PDF viewers — even those that do not honor
+ * the `/NeedAppearances` flag.
+ *
+ * @see PDF Reference 1.7, §12.5.5 — Appearance Streams
+ * @see PDF Reference 1.7, §12.7.4 — Field Appearance
+ */
+import { PdfContentStream } from "../core/pdf-stream.js";
+import { pdfNumber } from "../core/pdf-object.js";
+// =============================================================================
+// Text Field Appearance
+// =============================================================================
+/** Default padding inside the field rectangle (in points). */
+const FIELD_PADDING = 2;
+/**
+ * Generate an appearance stream for a text form field.
+ *
+ * Builds a minimal content stream that clips to the widget rect and
+ * draws the field value using the specified (or default) font.
+ *
+ * @returns The raw stream bytes and a resources dictionary string.
+ */
+export function generateTextFieldAppearance(options) {
+    const { value, rect, alignment = "left" } = options;
+    const fontName = options.fontName ?? "Helv";
+    // Derive bounding box dimensions from the widget rect
+    const x1 = rect[0] ?? 0;
+    const y1 = rect[1] ?? 0;
+    const x2 = rect[2] ?? x1;
+    const y2 = rect[3] ?? y1;
+    const width = Math.abs(x2 - x1);
+    const height = Math.abs(y2 - y1);
+    // Auto-size font: use ~70% of the field height, clamped to a reasonable range
+    let fontSize = options.fontSize ?? 0;
+    if (fontSize <= 0) {
+        fontSize = Math.max(4, Math.min(height * 0.7, 20));
+    }
+    // Approximate text width using 0.5 * fontSize per character (conservative estimate
+    // for Helvetica). This is intentionally simple — the appearance is a best-effort
+    // rendering; the authoritative value is in /V.
+    const approxCharWidth = fontSize * 0.5;
+    const textWidth = value.length * approxCharWidth;
+    // Compute horizontal offset based on alignment
+    let tx;
+    const usableWidth = width - 2 * FIELD_PADDING;
+    switch (alignment) {
+        case "center":
+            tx = FIELD_PADDING + Math.max(0, (usableWidth - textWidth) / 2);
+            break;
+        case "right":
+            tx = FIELD_PADDING + Math.max(0, usableWidth - textWidth);
+            break;
+        default:
+            tx = FIELD_PADDING;
+            break;
+    }
+    // Vertical centering: place baseline so the text is roughly centered
+    // Approximate ascent ≈ 0.75 * fontSize, descent ≈ -0.25 * fontSize
+    const ascent = fontSize * 0.75;
+    const descent = fontSize * 0.25;
+    const textHeight = ascent + descent;
+    const ty = (height - textHeight) / 2 + descent;
+    // Build the content stream
+    const cs = new PdfContentStream();
+    // Clip to the bounding box (form XObject coordinate space: 0,0 to width,height)
+    cs.rect(0, 0, width, height).clip().endPath();
+    // Draw the text
+    cs.beginText().setFont(fontName, fontSize).moveText(tx, ty).showText(value).endText();
+    const stream = cs.toUint8Array();
+    // Build a minimal resources dict referencing a standard Helvetica font.
+    // The font is declared inline as a Type1 font so the appearance stream
+    // is self-contained (no dependency on the page's resources).
+    const resources = `<< /Font << /${fontName} << /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >> >> >>`;
+    return { stream, resources };
+}
+// =============================================================================
+// Checkbox Appearance
+// =============================================================================
+/**
+ * Generate appearance streams for a checkbox form field.
+ *
+ * Returns two streams:
+ * - `streamOn`:  draws a checkmark (✓-like shape) inside the rect
+ * - `streamOff`: empty appearance (blank field)
+ *
+ * @param checked - Whether to generate the checked or unchecked variant
+ *                  (both are always returned; `checked` is ignored — both
+ *                  on and off streams are produced).
+ * @param rect - Widget annotation rectangle [x1, y1, x2, y2].
+ */
+export function generateCheckboxAppearance(_checked, rect) {
+    const x1 = rect[0] ?? 0;
+    const y1 = rect[1] ?? 0;
+    const x2 = rect[2] ?? x1;
+    const y2 = rect[3] ?? y1;
+    const width = Math.abs(x2 - x1);
+    const height = Math.abs(y2 - y1);
+    // --- "On" appearance: draw an X ---
+    const onCs = new PdfContentStream();
+    const inset = Math.min(width, height) * 0.15;
+    onCs
+        .save()
+        .setStrokeColor({ r: 0, g: 0, b: 0 })
+        .setLineWidth(Math.max(1, Math.min(width, height) * 0.1))
+        // First stroke of the X: bottom-left to top-right
+        .moveTo(inset, inset)
+        .lineTo(width - inset, height - inset)
+        .stroke()
+        // Second stroke of the X: top-left to bottom-right
+        .moveTo(inset, height - inset)
+        .lineTo(width - inset, inset)
+        .stroke()
+        .restore();
+    // --- "Off" appearance: empty ---
+    const offCs = new PdfContentStream();
+    // Intentionally empty — nothing to draw for unchecked state
+    return {
+        streamOn: onCs.toUint8Array(),
+        streamOff: offCs.toUint8Array()
+    };
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Build the BBox array string for a form XObject appearance stream.
+ * The bounding box is in the widget's coordinate space: [0 0 width height].
+ */
+export function buildAppearanceBBox(rect) {
+    const x1 = rect[0] ?? 0;
+    const y1 = rect[1] ?? 0;
+    const x2 = rect[2] ?? x1;
+    const y2 = rect[3] ?? y1;
+    const width = Math.abs(x2 - x1);
+    const height = Math.abs(y2 - y1);
+    return `[0 0 ${pdfNumber(width)} ${pdfNumber(height)}]`;
+}

package/dist/browser/modules/pdf/builder/image-utils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared image utilities for PDF generation.
+ *
+ * Centralises JPEG/PNG dimension parsing and PDF XObject writing so that
+ * both the builder (`document-builder.ts`) and the exporter (`pdf-exporter.ts`)
+ * share a single implementation.
+ */
+import type { PdfWriter } from "../core/pdf-writer.js";
+/**
+ * Parse image dimensions from raw bytes.
+ */
+export declare function parseImageDimensions(data: Uint8Array, format: "jpeg" | "png"): {
+    width: number;
+    height: number;
+};
+/**
+ * Read width/height from a PNG IHDR chunk (bytes 16-23).
+ */
+export declare function parsePngDimensions(data: Uint8Array): {
+    width: number;
+    height: number;
+};
+/**
+ * Read width/height from JPEG SOF marker.
+ *
+ * Correctly excludes non-SOF markers in the 0xC0-0xCF range:
+ * - 0xC4 = DHT (Define Huffman Table)
+ * - 0xC8 = JPG (reserved)
+ * - 0xCC = DAC (Define Arithmetic Coding)
+ */
+export declare function parseJpegDimensions(data: Uint8Array): {
+    width: number;
+    height: number;
+};
+/**
+ * Write an image XObject (JPEG or PNG) to the writer.
+ * Returns the allocated object number.
+ */
+export declare function writeImageXObject(writer: PdfWriter, data: Uint8Array, format: "jpeg" | "png"): number;

package/dist/browser/modules/pdf/builder/image-utils.js

@@ -0,0 +1,129 @@
+/**
+ * Shared image utilities for PDF generation.
+ *
+ * Centralises JPEG/PNG dimension parsing and PDF XObject writing so that
+ * both the builder (`document-builder.ts`) and the exporter (`pdf-exporter.ts`)
+ * share a single implementation.
+ */
+import { PdfDict, pdfRef, pdfNumber } from "../core/pdf-object.js";
+import { decodePng } from "../render/png-decoder.js";
+// =============================================================================
+// Image Dimension Parsing
+// =============================================================================
+/**
+ * Parse image dimensions from raw bytes.
+ */
+export function parseImageDimensions(data, format) {
+    if (format === "png") {
+        return parsePngDimensions(data);
+    }
+    return parseJpegDimensions(data);
+}
+/**
+ * Read width/height from a PNG IHDR chunk (bytes 16-23).
+ */
+export function parsePngDimensions(data) {
+    // PNG header: 8 byte signature, then IHDR chunk: 4 byte length, 4 byte type, 4 byte width, 4 byte height
+    if (data.length >= 24 &&
+        data[12] === 0x49 &&
+        data[13] === 0x48 &&
+        data[14] === 0x44 &&
+        data[15] === 0x52) {
+        const width = (data[16] << 24) | (data[17] << 16) | (data[18] << 8) | data[19];
+        const height = (data[20] << 24) | (data[21] << 16) | (data[22] << 8) | data[23];
+        return { width, height };
+    }
+    return { width: 1, height: 1 };
+}
+/**
+ * Read width/height from JPEG SOF marker.
+ *
+ * Correctly excludes non-SOF markers in the 0xC0-0xCF range:
+ * - 0xC4 = DHT (Define Huffman Table)
+ * - 0xC8 = JPG (reserved)
+ * - 0xCC = DAC (Define Arithmetic Coding)
+ */
+export function parseJpegDimensions(data) {
+    let offset = 2; // skip SOI marker
+    while (offset < data.length - 1) {
+        // Skip padding 0xFF bytes
+        while (offset < data.length && data[offset] === 0xff && data[offset + 1] === 0xff) {
+            offset++;
+        }
+        if (offset >= data.length - 1 || data[offset] !== 0xff) {
+            break;
+        }
+        const marker = data[offset + 1];
+        const isSof = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+        if (isSof && offset + 8 < data.length) {
+            return {
+                width: (data[offset + 7] << 8) | data[offset + 8],
+                height: (data[offset + 5] << 8) | data[offset + 6]
+            };
+        }
+        if (offset + 3 >= data.length) {
+            break;
+        }
+        const segLen = (data[offset + 2] << 8) | data[offset + 3];
+        offset += 2 + segLen;
+    }
+    return { width: 1, height: 1 };
+}
+// =============================================================================
+// PDF Image XObject Writing
+// =============================================================================
+/**
+ * Write an image XObject (JPEG or PNG) to the writer.
+ * Returns the allocated object number.
+ */
+export function writeImageXObject(writer, data, format) {
+    if (format === "png") {
+        return writePngImageXObject(writer, data);
+    }
+    return writeJpegImageXObject(writer, data);
+}
+/**
+ * Write a JPEG image using DCTDecode (raw JPEG data embedded directly).
+ */
+function writeJpegImageXObject(writer, data) {
+    const objNum = writer.allocObject();
+    const dims = parseJpegDimensions(data);
+    const dict = new PdfDict()
+        .set("Type", "/XObject")
+        .set("Subtype", "/Image")
+        .set("Width", pdfNumber(dims.width))
+        .set("Height", pdfNumber(dims.height))
+        .set("ColorSpace", "/DeviceRGB")
+        .set("BitsPerComponent", "8")
+        .set("Filter", "/DCTDecode");
+    writer.addStreamObject(objNum, dict, data);
+    return objNum;
+}
+/**
+ * Write a PNG image: decode to raw RGB, create SMask for alpha if needed.
+ */
+function writePngImageXObject(writer, data) {
+    const png = decodePng(data);
+    const objNum = writer.allocObject();
+    const dict = new PdfDict()
+        .set("Type", "/XObject")
+        .set("Subtype", "/Image")
+        .set("Width", pdfNumber(png.width))
+        .set("Height", pdfNumber(png.height))
+        .set("ColorSpace", "/DeviceRGB")
+        .set("BitsPerComponent", pdfNumber(png.bitsPerComponent));
+    if (png.alpha) {
+        const smaskObjNum = writer.allocObject();
+        const smaskDict = new PdfDict()
+            .set("Type", "/XObject")
+            .set("Subtype", "/Image")
+            .set("Width", pdfNumber(png.width))
+            .set("Height", pdfNumber(png.height))
+            .set("ColorSpace", "/DeviceGray")
+            .set("BitsPerComponent", "8");
+        writer.addStreamObject(smaskObjNum, smaskDict, png.alpha);
+        dict.set("SMask", pdfRef(smaskObjNum));
+    }
+    writer.addStreamObject(objNum, dict, png.pixels);
+    return objNum;
+}

package/dist/browser/modules/pdf/builder/pdf-editor.d.ts

@@ -0,0 +1,230 @@
+/**
+ * PDF editor — modify existing PDF documents.
+ *
+ * Supports:
+ * - Adding new pages with free-form content
+ * - Adding text/shapes/images to existing pages (overlay)
+ * - Filling form fields (AcroForm)
+ * - Copying pages from other PDFs (merge)
+ * - Preserving page properties (Rotate, CropBox, etc.) and metadata
+ *
+ * Note: save() rebuilds the PDF from scratch rather than using incremental
+ * updates. This is simpler and more reliable but means object numbers change
+ * and existing digital signatures will be invalidated.
+ *
+ * @example Edit an existing PDF:
+ * ```typescript
+ * import { PdfEditor } from "@cj-tech-master/excelts/pdf";
+ *
+ * const editor = PdfEditor.load(existingPdfBytes);
+ * editor.getPage(0).drawText("APPROVED", { x: 200, y: 400, fontSize: 48, color: { r: 0, g: 0.5, b: 0 } });
+ * editor.setFormField("name", "John Doe");
+ * const result = await editor.save();
+ * ```
+ */
+import type { PdfContentStream } from "../core/pdf-stream.js";
+import type { PdfFormField } from "../reader/form-extractor.js";
+import { PdfPageBuilder } from "./document-builder.js";
+import type { DrawTextOptions, DrawRectOptions, DrawCircleOptions, DrawEllipseOptions, DrawLineOptions, DrawImageOptions, DrawPathOptions, PathOp, PageOptions, AnnotationOptions, FormFieldOptions, PdfSignatureOptions } from "./document-builder.js";
+/** Options for loading a PDF for editing. */
+export interface LoadOptions {
+    /** Password for encrypted PDFs. */
+    password?: string;
+}
+/**
+ * Proxy for an existing page that allows overlaying new content.
+ * New content is drawn on top of existing content via a separate content stream.
+ */
+export declare class PdfEditorPage {
+    /** Page width in points. */
+    get width(): number;
+    /** Page height in points. */
+    get height(): number;
+    /**
+     * Measure the width of a text string in points.
+     */
+    measureText(text: string, options?: {
+        fontSize?: number;
+        fontFamily?: string;
+        bold?: boolean;
+        italic?: boolean;
+    }): number;
+    /**
+     * Draw text on this existing page (overlaid on top).
+     */
+    drawText(text: string, options: DrawTextOptions): this;
+    /**
+     * Draw a rectangle on this existing page.
+     */
+    drawRect(options: DrawRectOptions): this;
+    /**
+     * Draw a circle on this existing page.
+     */
+    drawCircle(options: DrawCircleOptions): this;
+    /**
+     * Draw an ellipse on this existing page.
+     */
+    drawEllipse(options: DrawEllipseOptions): this;
+    /**
+     * Draw a line on this existing page.
+     */
+    drawLine(options: DrawLineOptions): this;
+    /**
+     * Draw an image on this existing page.
+     */
+    drawImage(options: DrawImageOptions): this;
+    /**
+     * Get the raw overlay content stream.
+     */
+    getContentStream(): PdfContentStream;
+    /**
+     * Add an annotation to this existing page (Highlight, Text, FreeText, Stamp, etc.).
+     */
+    addAnnotation(options: AnnotationOptions): this;
+    /**
+     * Add a form field to this existing page.
+     */
+    addFormField(options: FormFieldOptions): this;
+    /**
+     * Draw an SVG path on this existing page.
+     */
+    drawSvgPath(d: string, options?: DrawPathOptions): this;
+    /**
+     * Draw a complex path from a list of path operations.
+     */
+    drawPath(ops: PathOp[], options?: DrawPathOptions): this;
+}
+/**
+ * Editor for modifying existing PDF documents.
+ *
+ * Load an existing PDF, overlay content on existing pages, fill form fields,
+ * add new pages, copy pages from other documents, and save.
+ */
+export declare class PdfEditor {
+    private _doc;
+    private _password;
+    private _pages;
+    private _newPages;
+    private _fontManager;
+    private _formFieldUpdates;
+    private _copiedPages;
+    private _signaturePlaceholder;
+    private constructor();
+    /**
+     * Load a PDF for editing.
+     *
+     * @param data - Raw PDF file bytes
+     * @param options - Load options (e.g., password)
+     * @returns A PdfEditor instance
+     */
+    static load(data: Uint8Array, options?: LoadOptions): PdfEditor;
+    /** Number of existing pages. */
+    get pageCount(): number;
+    /**
+     * Get an existing page for editing (overlaying content).
+     *
+     * @param index - 0-based page index
+     */
+    getPage(index: number): PdfEditorPage;
+    /**
+     * Add a new blank page to the end of the document.
+     */
+    addPage(options?: PageOptions): PdfPageBuilder;
+    /**
+     * Remove a page from the document.
+     *
+     * @param index - 0-based page index (of original pages only)
+     */
+    removePage(index: number): this;
+    /**
+     * Set the rotation of an existing page.
+     *
+     * @param index - 0-based page index (of original pages only)
+     * @param degrees - Rotation in degrees (must be 0, 90, 180, or 270)
+     */
+    rotatePage(index: number, degrees: number): this;
+    /**
+     * Split the document: save each page (or a subset) as a separate PDF.
+     *
+     * @param pageIndices - 0-based page indices to extract. Omit to split all pages.
+     * @returns Array of Uint8Array, one per requested page.
+     */
+    splitPages(pageIndices?: number[]): Promise<Uint8Array[]>;
+    /**
+     * Embed a TrueType font for Unicode/CJK support.
+     */
+    embedFont(fontBytes: Uint8Array): this;
+    /**
+     * Set the value of a form field.
+     * The field is identified by its fully qualified name (e.g., "form.address.city").
+     *
+     * @param fieldName - Fully qualified field name
+     * @param value - New value to set
+     */
+    setFormField(fieldName: string, value: string): this;
+    /**
+     * Set multiple form field values at once.
+     *
+     * @param fields - Object mapping field names to values
+     */
+    setFormFields(fields: Record<string, string>): this;
+    /**
+     * Get current form fields (before any modifications).
+     */
+    getFormFields(): PdfFormField[];
+    /**
+     * Copy pages from another PDF document into this document.
+     *
+     * @param sourcePdf - Raw bytes of the source PDF
+     * @param pageIndices - 0-based page indices to copy. Omit to copy all pages.
+     * @param options - Load options for the source PDF (e.g., password)
+     */
+    copyPagesFrom(sourcePdf: Uint8Array, pageIndices?: number[], options?: LoadOptions): this;
+    /**
+     * Save the modified PDF.
+     *
+     * Rebuilds the PDF from scratch — content streams, resources, and page
+     * properties are deep-cloned into a new document. Original metadata and
+     * XMP streams are preserved. Digital signatures will be invalidated.
+     *
+     * @returns The modified PDF as Uint8Array
+     */
+    save(): Promise<Uint8Array>;
+    /**
+     * Save the modified PDF using incremental update.
+     *
+     * Appends new/modified objects after the original PDF bytes, preserving the
+     * original data byte-for-byte. This is ideal for overlays and form field
+     * updates on existing pages — it preserves digital signatures on unmodified
+     * content and produces smaller output.
+     *
+     * Falls back to {@link save} (full rebuild) if structural changes are
+     * present (new pages, copied pages, or removed pages).
+     *
+     * @returns The modified PDF as Uint8Array
+     */
+    saveIncremental(): Promise<Uint8Array>;
+    /** Page-level keys to preserve when rebuilding page dicts. */
+    private static readonly _PAGE_PRESERVE_KEYS;
+    /**
+     * Sign this PDF with a digital signature.
+     *
+     * Performs a full save with an embedded PKCS#7 signature placeholder,
+     * then fills in the real CMS SignedData.
+     *
+     * @param options - Certificate, private key, and optional signer metadata
+     * @returns The signed PDF as Uint8Array
+     *
+     * @example
+     * ```typescript
+     * const editor = PdfEditor.load(pdfBytes);
+     * const signed = await editor.sign({
+     *   certificate: certDerBytes,
+     *   privateKey: pkcs8DerBytes,
+     *   name: "Jane Doe",
+     *   reason: "Approval"
+     * });
+     * ```
+     */
+    sign(options: PdfSignatureOptions): Promise<Uint8Array>;
+}