@cj-tech-master/excelts 9.1.0 → 9.2.0

package/dist/esm/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/esm/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;
+}