@cj-tech-master/excelts 8.0.0 → 8.1.0

package/dist/browser/modules/pdf/reader/form-extractor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * PDF form field (AcroForm) extractor.
+ *
+ * Extracts interactive form fields from a PDF's `/AcroForm` dictionary.
+ * Supports all standard field types:
+ * - **Text** (`/Tx`) — Text input fields
+ * - **Button** (`/Btn`) — Checkboxes, radio buttons, push buttons
+ * - **Choice** (`/Ch`) — Dropdowns (combo boxes) and list boxes
+ * - **Signature** (`/Sig`) — Digital signature fields
+ *
+ * Handles field hierarchies (parent/child), inherited values, and default appearances.
+ *
+ * @see PDF Reference 1.7, §12.7 - Interactive Forms
+ */
+import type { PdfDocument } from "./pdf-document.js";
+/** Type of form field. */
+export type PdfFormFieldType = "text" | "checkbox" | "radio" | "dropdown" | "listbox" | "button" | "signature" | "unknown";
+/** A single form field extracted from the PDF. */
+export interface PdfFormField {
+    /** Fully qualified field name (e.g. "form1.address.city") */
+    name: string;
+    /** Field type */
+    type: PdfFormFieldType;
+    /** Current value of the field */
+    value: string;
+    /** Default value (/DV entry) */
+    defaultValue: string;
+    /** Whether the field is read-only */
+    readOnly: boolean;
+    /** Whether the field is required */
+    required: boolean;
+    /** For choice fields: the list of available options */
+    options: string[];
+    /** For checkboxes/radio buttons: the export value when checked */
+    exportValue: string;
+    /** Field flags (/Ff entry) — raw bit field */
+    flags: number;
+}
+/**
+ * Extract form fields from a PDF document.
+ *
+ * Reads the `/AcroForm` dictionary from the catalog and recursively
+ * traverses the field tree.
+ *
+ * @param doc - The PDF document
+ * @returns Array of extracted form fields
+ */
+export declare function extractFormFields(doc: PdfDocument): PdfFormField[];

package/dist/browser/modules/pdf/reader/form-extractor.js

@@ -0,0 +1,355 @@
+/**
+ * PDF form field (AcroForm) extractor.
+ *
+ * Extracts interactive form fields from a PDF's `/AcroForm` dictionary.
+ * Supports all standard field types:
+ * - **Text** (`/Tx`) — Text input fields
+ * - **Button** (`/Btn`) — Checkboxes, radio buttons, push buttons
+ * - **Choice** (`/Ch`) — Dropdowns (combo boxes) and list boxes
+ * - **Signature** (`/Sig`) — Digital signature fields
+ *
+ * Handles field hierarchies (parent/child), inherited values, and default appearances.
+ *
+ * @see PDF Reference 1.7, §12.7 - Interactive Forms
+ */
+import { isPdfArray, isPdfRef, dictGetName, dictGetNumber, decodePdfStringBytes } from "./pdf-parser.js";
+import { getDictStringValue } from "./reader-utils.js";
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Extract form fields from a PDF document.
+ *
+ * Reads the `/AcroForm` dictionary from the catalog and recursively
+ * traverses the field tree.
+ *
+ * @param doc - The PDF document
+ * @returns Array of extracted form fields
+ */
+export function extractFormFields(doc) {
+    try {
+        const catalog = doc.getCatalog();
+        const acroFormObj = catalog.get("AcroForm");
+        if (!acroFormObj) {
+            return [];
+        }
+        const acroForm = doc.derefDict(acroFormObj);
+        if (!acroForm) {
+            return [];
+        }
+        const fieldsObj = acroForm.get("Fields");
+        if (!fieldsObj) {
+            return [];
+        }
+        const fieldsArr = doc.deref(fieldsObj);
+        if (!isPdfArray(fieldsArr)) {
+            return [];
+        }
+        const fields = [];
+        const visited = new Set();
+        for (const fieldRef of fieldsArr) {
+            collectFields(fieldRef, doc, "", fields, visited);
+        }
+        return fields;
+    }
+    catch {
+        return [];
+    }
+}
+// =============================================================================
+// Field Tree Traversal
+// =============================================================================
+/** Field flags from PDF spec §12.7.3 */
+const FLAG_READ_ONLY = 1 << 0;
+const FLAG_REQUIRED = 1 << 1;
+// Button-specific
+const FLAG_PUSHBUTTON = 1 << 16;
+const FLAG_RADIO = 1 << 15;
+// Choice-specific
+const FLAG_COMBO = 1 << 17;
+/** Maximum depth for parent traversal to prevent cycles in malformed PDFs */
+const MAX_INHERIT_DEPTH = 20;
+function collectFields(fieldObj, doc, parentName, result, visited) {
+    // Track visited objects to avoid cycles
+    if (isPdfRef(fieldObj)) {
+        if (visited.has(fieldObj.objNum)) {
+            return;
+        }
+        visited.add(fieldObj.objNum);
+    }
+    const dict = doc.derefDict(fieldObj);
+    if (!dict) {
+        return;
+    }
+    // Build the fully qualified field name
+    const partialName = getDictStringValue(dict, "T", doc);
+    const fullName = parentName
+        ? partialName
+            ? `${parentName}.${partialName}`
+            : parentName
+        : partialName;
+    // Check for children (/Kids)
+    const kidsObj = dict.get("Kids");
+    if (kidsObj) {
+        const kids = doc.deref(kidsObj);
+        if (isPdfArray(kids)) {
+            // Check if kids are field nodes or widget nodes
+            // If kids have /T entries, they are field nodes (continue recursion)
+            // If kids don't have /T, they are widget annotations — treat parent as the field
+            let hasFieldChildren = false;
+            for (const kid of kids) {
+                const kidDict = doc.derefDict(kid);
+                if (kidDict && kidDict.has("T")) {
+                    hasFieldChildren = true;
+                    break;
+                }
+            }
+            if (hasFieldChildren) {
+                // Recurse into child fields
+                for (const kid of kids) {
+                    collectFields(kid, doc, fullName, result, visited);
+                }
+                return;
+            }
+            // Kids are widgets — extract value from first kid or parent
+            // For radio buttons, collect export values from kids
+            const ft = resolveFieldType(dict, doc);
+            if (ft === "Btn") {
+                const ff = resolveFieldFlags(dict, doc);
+                if ((ff & FLAG_RADIO) !== 0 && (ff & FLAG_PUSHBUTTON) === 0) {
+                    // Radio button: current value is on the parent, export values on kids
+                    const field = parseRadioField(dict, kids, fullName, ff, doc);
+                    if (field) {
+                        result.push(field);
+                    }
+                    return;
+                }
+            }
+        }
+    }
+    // Leaf field — extract its properties
+    const ft = resolveFieldType(dict, doc);
+    if (!ft) {
+        return; // Not a real field (no /FT)
+    }
+    const field = parseField(dict, fullName, ft, doc);
+    if (field) {
+        result.push(field);
+    }
+}
+// =============================================================================
+// Field Parsing
+// =============================================================================
+/**
+ * Resolve /FT (field type) which may be inherited from parent.
+ */
+function resolveFieldType(dict, doc, depth = 0) {
+    const ft = dictGetName(dict, "FT");
+    if (ft) {
+        return ft;
+    }
+    if (depth >= MAX_INHERIT_DEPTH) {
+        return undefined;
+    }
+    // Check parent
+    const parent = dict.get("Parent");
+    if (parent) {
+        const parentDict = doc.derefDict(parent);
+        if (parentDict) {
+            return resolveFieldType(parentDict, doc, depth + 1);
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve /Ff (field flags) which may be inherited from parent.
+ */
+function resolveFieldFlags(dict, doc, depth = 0) {
+    const ff = dictGetNumber(dict, "Ff");
+    if (ff !== undefined) {
+        return ff;
+    }
+    if (depth >= MAX_INHERIT_DEPTH) {
+        return 0;
+    }
+    const parent = dict.get("Parent");
+    if (parent) {
+        const parentDict = doc.derefDict(parent);
+        if (parentDict) {
+            return resolveFieldFlags(parentDict, doc, depth + 1);
+        }
+    }
+    return 0;
+}
+function parseField(dict, name, ft, doc) {
+    const ff = resolveFieldFlags(dict, doc);
+    const value = getFieldValue(dict, doc);
+    const defaultValue = getDictStringValue(dict, "DV", doc);
+    const type = classifyFieldType(ft, ff);
+    let options = [];
+    let exportValue = "";
+    if (ft === "Ch") {
+        options = parseChoiceOptions(dict, doc);
+    }
+    if (ft === "Btn" && (ff & FLAG_PUSHBUTTON) === 0 && (ff & FLAG_RADIO) === 0) {
+        // Checkbox — extract export value from /AP /N keys
+        exportValue = parseCheckboxExportValue(dict, doc);
+    }
+    return {
+        name: name || "(unnamed)",
+        type,
+        value,
+        defaultValue,
+        readOnly: (ff & FLAG_READ_ONLY) !== 0,
+        required: (ff & FLAG_REQUIRED) !== 0,
+        options,
+        exportValue,
+        flags: ff
+    };
+}
+function parseRadioField(parentDict, kids, name, ff, doc) {
+    const value = getFieldValue(parentDict, doc);
+    const defaultValue = getDictStringValue(parentDict, "DV", doc);
+    // Collect export values from kid appearance dictionaries
+    const options = [];
+    for (const kid of kids) {
+        const kidDict = doc.derefDict(kid);
+        if (!kidDict) {
+            continue;
+        }
+        const apDict = doc.derefDict(kidDict.get("AP"));
+        if (!apDict) {
+            continue;
+        }
+        const nDict = doc.derefDict(apDict.get("N"));
+        if (!nDict) {
+            continue;
+        }
+        // Keys of /AP /N are the possible states (e.g. "/Choice1", "/Off")
+        for (const key of nDict.keys()) {
+            if (key !== "Off" && !options.includes(key)) {
+                options.push(key);
+            }
+        }
+    }
+    return {
+        name: name || "(unnamed)",
+        type: "radio",
+        value,
+        defaultValue,
+        readOnly: (ff & FLAG_READ_ONLY) !== 0,
+        required: (ff & FLAG_REQUIRED) !== 0,
+        options,
+        exportValue: "",
+        flags: ff
+    };
+}
+function classifyFieldType(ft, ff) {
+    switch (ft) {
+        case "Tx":
+            return "text";
+        case "Btn":
+            if ((ff & FLAG_PUSHBUTTON) !== 0) {
+                return "button";
+            }
+            if ((ff & FLAG_RADIO) !== 0) {
+                return "radio";
+            }
+            return "checkbox";
+        case "Ch":
+            if ((ff & FLAG_COMBO) !== 0) {
+                return "dropdown";
+            }
+            return "listbox";
+        case "Sig":
+            return "signature";
+        default:
+            return "unknown";
+    }
+}
+function parseChoiceOptions(dict, doc) {
+    const optObj = dict.get("Opt");
+    if (!optObj) {
+        return [];
+    }
+    const optArr = doc.deref(optObj);
+    if (!isPdfArray(optArr)) {
+        return [];
+    }
+    const options = [];
+    for (const item of optArr) {
+        const resolved = doc.deref(item);
+        if (typeof resolved === "string") {
+            options.push(resolved);
+        }
+        else if (resolved instanceof Uint8Array) {
+            options.push(decodePdfStringBytes(resolved));
+        }
+        else if (isPdfArray(resolved) && resolved.length >= 2) {
+            // [exportValue, displayValue] pair
+            const display = doc.deref(resolved[1]);
+            if (typeof display === "string") {
+                options.push(display);
+            }
+            else if (display instanceof Uint8Array) {
+                options.push(decodePdfStringBytes(display));
+            }
+        }
+    }
+    return options;
+}
+function parseCheckboxExportValue(dict, doc) {
+    // The export value is the key in /AP /N that isn't "Off"
+    const apDict = doc.derefDict(dict.get("AP"));
+    if (!apDict) {
+        return "Yes"; // Default per spec
+    }
+    const nDict = doc.derefDict(apDict.get("N"));
+    if (!nDict) {
+        return "Yes";
+    }
+    for (const key of nDict.keys()) {
+        if (key !== "Off") {
+            return key;
+        }
+    }
+    return "Yes";
+}
+// =============================================================================
+// Value Extraction
+// =============================================================================
+/** Get the field value (/V entry), resolving from parent if needed. */
+function getFieldValue(dict, doc, depth = 0) {
+    const val = dict.get("V");
+    if (val !== undefined) {
+        return resolveValue(val, doc);
+    }
+    if (depth >= MAX_INHERIT_DEPTH) {
+        return "";
+    }
+    // Inherit from parent
+    const parent = dict.get("Parent");
+    if (parent) {
+        const parentDict = doc.derefDict(parent);
+        if (parentDict) {
+            return getFieldValue(parentDict, doc, depth + 1);
+        }
+    }
+    return "";
+}
+function resolveValue(val, doc) {
+    const resolved = doc.deref(val);
+    if (typeof resolved === "string") {
+        return resolved;
+    }
+    if (resolved instanceof Uint8Array) {
+        return decodePdfStringBytes(resolved);
+    }
+    if (typeof resolved === "number") {
+        return String(resolved);
+    }
+    if (typeof resolved === "boolean") {
+        return resolved ? "true" : "false";
+    }
+    return "";
+}

package/dist/browser/modules/pdf/reader/image-extractor.d.ts

@@ -0,0 +1,55 @@
+/**
+ * PDF image extraction.
+ *
+ * Extracts images from PDF pages including:
+ * - Inline images (BI/ID/EI operators)
+ * - XObject images (/Subtype /Image)
+ * - Images with various color spaces and filters
+ *
+ * Supported image formats:
+ * - JPEG (DCTDecode) — extracted as-is
+ * - JPEG2000 (JPXDecode) — extracted as-is
+ * - Raw/Flate-compressed pixel data — extracted with metadata
+ * - CCITT fax — extracted as-is
+ *
+ * @see PDF Reference 1.7, §4.8 - Images
+ */
+import type { PdfDocument } from "./pdf-document.js";
+import type { PdfDictValue } from "./pdf-parser.js";
+/**
+ * An extracted image from a PDF page.
+ */
+export interface ExtractedImage {
+    /** Image index within the page (0-based) */
+    index: number;
+    /** Image width in pixels */
+    width: number;
+    /** Image height in pixels */
+    height: number;
+    /** Bits per component */
+    bitsPerComponent: number;
+    /** Color space name */
+    colorSpace: string;
+    /** Number of color components (1=gray, 3=RGB, 4=CMYK) */
+    components: number;
+    /**
+     * Image data format:
+     * - "jpeg" — raw JPEG data (can be written directly as .jpg)
+     * - "jpx" — JPEG 2000 data
+     * - "raw" — raw pixel data (RGB/CMYK/Gray, decompressed)
+     * - "ccitt" — CCITT fax compressed data
+     */
+    format: "jpeg" | "jpx" | "raw" | "ccitt" | "jbig2";
+    /** The image data */
+    data: Uint8Array;
+    /** Alpha mask data (if present) — same dimensions, 1 component, 8 bits */
+    alphaMask: Uint8Array | null;
+    /** Filter name from the original stream */
+    filter: string;
+    /** XObject name (if it was a named XObject) */
+    name: string;
+}
+/**
+ * Extract all images from a PDF page.
+ */
+export declare function extractImagesFromPage(pageDict: PdfDictValue, doc: PdfDocument): ExtractedImage[];

package/dist/browser/modules/pdf/reader/image-extractor.js

@@ -0,0 +1,220 @@
+/**
+ * PDF image extraction.
+ *
+ * Extracts images from PDF pages including:
+ * - Inline images (BI/ID/EI operators)
+ * - XObject images (/Subtype /Image)
+ * - Images with various color spaces and filters
+ *
+ * Supported image formats:
+ * - JPEG (DCTDecode) — extracted as-is
+ * - JPEG2000 (JPXDecode) — extracted as-is
+ * - Raw/Flate-compressed pixel data — extracted with metadata
+ * - CCITT fax — extracted as-is
+ *
+ * @see PDF Reference 1.7, §4.8 - Images
+ */
+import { isPdfRef, isPdfArray, dictGetName, dictGetNumber } from "./pdf-parser.js";
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Extract all images from a PDF page.
+ */
+export function extractImagesFromPage(pageDict, doc) {
+    const images = [];
+    // Get page resources (centralized with cycle protection)
+    const resources = doc.resolvePageResources(pageDict);
+    const xobjects = resources.get("XObject");
+    if (!xobjects) {
+        return images;
+    }
+    const xobjDict = doc.derefDict(xobjects);
+    if (!xobjDict) {
+        return images;
+    }
+    let index = 0;
+    for (const [name, ref] of xobjDict) {
+        const result = doc.derefStreamWithObjNum(ref);
+        if (!result) {
+            continue;
+        }
+        const streamDict = result.stream.dict;
+        const subtype = dictGetName(streamDict, "Subtype");
+        if (subtype !== "Image") {
+            continue;
+        }
+        const image = extractImage(name, result.stream, streamDict, doc, index, result.objNum, result.gen);
+        if (image) {
+            images.push(image);
+            index++;
+        }
+    }
+    return images;
+}
+// =============================================================================
+// Image Extraction
+// =============================================================================
+function extractImage(name, stream, dict, doc, index, objNum = 0, gen = 0) {
+    const width = dictGetNumber(dict, "Width") ?? dictGetNumber(dict, "W") ?? 0;
+    const height = dictGetNumber(dict, "Height") ?? dictGetNumber(dict, "H") ?? 0;
+    const bpc = dictGetNumber(dict, "BitsPerComponent") ?? dictGetNumber(dict, "BPC") ?? 8;
+    if (width === 0 || height === 0) {
+        return null;
+    }
+    // Determine color space
+    const { colorSpace, components } = resolveColorSpace(dict, doc);
+    // Determine filter to understand the image format
+    const filter = getFilterName(dict);
+    // Extract image data based on filter
+    // For all formats, use getStreamData which handles decryption and filter decoding
+    let data;
+    let format;
+    if (filter === "DCTDecode" || filter === "DCT") {
+        // JPEG — use getStreamData which handles decryption properly
+        data = doc.getStreamData(stream, objNum, gen);
+        format = "jpeg";
+    }
+    else if (filter === "JPXDecode") {
+        data = doc.getStreamData(stream, objNum, gen);
+        format = "jpx";
+    }
+    else if (filter === "CCITTFaxDecode" || filter === "CCF") {
+        data = doc.getStreamData(stream, objNum, gen);
+        format = "ccitt";
+    }
+    else if (filter === "JBIG2Decode") {
+        data = doc.getStreamData(stream, objNum, gen);
+        format = "jbig2";
+    }
+    else {
+        // Decode all filters to get raw pixel data
+        data = doc.getStreamData(stream, objNum, gen);
+        format = "raw";
+    }
+    // Extract soft mask (alpha channel)
+    let alphaMask = null;
+    const smaskRef = dict.get("SMask");
+    if (smaskRef) {
+        const smaskResult = doc.derefStreamWithObjNum(smaskRef);
+        if (smaskResult) {
+            alphaMask = doc.getStreamData(smaskResult.stream, smaskResult.objNum, smaskResult.gen);
+        }
+    }
+    return {
+        index,
+        width,
+        height,
+        bitsPerComponent: bpc,
+        colorSpace,
+        components,
+        format,
+        data,
+        alphaMask,
+        filter,
+        name
+    };
+}
+// =============================================================================
+// Color Space Resolution
+// =============================================================================
+function resolveColorSpace(dict, doc) {
+    const cs = dict.get("ColorSpace") ?? dict.get("CS");
+    if (typeof cs === "string") {
+        return colorSpaceInfo(cs);
+    }
+    if (isPdfArray(cs) && cs.length > 0) {
+        const csName = cs[0];
+        if (typeof csName === "string") {
+            if (csName === "ICCBased") {
+                // ICC-based color space — get N from the profile stream
+                if (cs.length > 1) {
+                    const profileStream = doc.derefStream(cs[1]);
+                    if (profileStream) {
+                        const n = dictGetNumber(profileStream.dict, "N") ?? 3;
+                        return {
+                            colorSpace: "ICCBased",
+                            components: n
+                        };
+                    }
+                }
+                return { colorSpace: "ICCBased", components: 3 };
+            }
+            if (csName === "Indexed" || csName === "I") {
+                return { colorSpace: "Indexed", components: 1 };
+            }
+            if (csName === "Separation") {
+                return { colorSpace: "Separation", components: 1 };
+            }
+            if (csName === "DeviceN") {
+                const numComponents = isPdfArray(cs[1]) ? cs[1].length : 1;
+                return { colorSpace: "DeviceN", components: numComponents };
+            }
+            return colorSpaceInfo(csName);
+        }
+    }
+    if (isPdfRef(cs)) {
+        const resolved = doc.deref(cs);
+        if (typeof resolved === "string") {
+            return colorSpaceInfo(resolved);
+        }
+        if (isPdfArray(resolved) && resolved.length > 0 && typeof resolved[0] === "string") {
+            return resolveColorSpace(new Map([["ColorSpace", resolved]]), doc);
+        }
+    }
+    return { colorSpace: "DeviceRGB", components: 3 };
+}
+function colorSpaceInfo(name) {
+    switch (name) {
+        case "DeviceGray":
+        case "G":
+        case "CalGray":
+            return { colorSpace: name, components: 1 };
+        case "DeviceRGB":
+        case "RGB":
+        case "CalRGB":
+            return { colorSpace: name, components: 3 };
+        case "DeviceCMYK":
+        case "CMYK":
+            return { colorSpace: name, components: 4 };
+        default:
+            return { colorSpace: name, components: 3 };
+    }
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Get the image-specific filter name from a stream dictionary.
+ * For filter chains, finds the last image-specific filter (DCT, JPX, CCITT, JBIG2).
+ * For non-image-specific chains (e.g., just FlateDecode), returns that filter.
+ */
+function getFilterName(dict) {
+    const filter = dict.get("Filter") ?? dict.get("F");
+    if (typeof filter === "string") {
+        return filter;
+    }
+    if (isPdfArray(filter) && filter.length > 0) {
+        // Look for the last image-specific filter in the chain
+        const imageFilters = new Set([
+            "DCTDecode",
+            "DCT",
+            "JPXDecode",
+            "CCITTFaxDecode",
+            "CCF",
+            "JBIG2Decode"
+        ]);
+        for (let i = filter.length - 1; i >= 0; i--) {
+            const f = filter[i];
+            if (typeof f === "string" && imageFilters.has(f)) {
+                return f;
+            }
+        }
+        // No image-specific filter found — return the first filter
+        const first = filter[0];
+        if (typeof first === "string") {
+            return first;
+        }
+    }
+    return "";
+}