@jasy/pdf 1.0.0-alpha.7 → 1.0.0-alpha.8

package/dist/utils/pdf-object-manager.d.ts

@@ -7,6 +7,7 @@ import type { FontDecoration } from "../text/text-decoration.js";
 import { StructTree } from "./struct-tree.js";
 import { OutlineBuilder } from "./outline.js";
 import { DestRegistry } from "./dest-registry.js";
+import { AcroFormCollector } from "../forms/acroform.js";
 import type { PDFConfig } from "../renderer/pdf-document-class.js";
 import type { FontMetrics } from "./font-metrics.js";
 interface FontIndexes {
@@ -47,6 +48,7 @@ export declare class PDFObjectManager implements FontMetrics {
     private overflowPolicy;
     private security?;
     private encJobs;
+    private strJobs;
     private encryptObjNum?;
     private _struct;
     get struct(): StructTree;
@@ -54,6 +56,8 @@ export declare class PDFObjectManager implements FontMetrics {
     get outline(): OutlineBuilder;
     private _dests;
     get dests(): DestRegistry;
+    private _acroform;
+    get acroform(): AcroFormCollector;
     constructor();
     addObject(content: string): number;
     replaceObject(objectNumber: number, content: string): void;
@@ -61,9 +65,23 @@ export declare class PDFObjectManager implements FontMetrics {
     setOverflowPolicy(policy: OverflowPolicy): void;
     getOverflowPolicy(): OverflowPolicy;
     private encToken;
+    private strToken;
+    /**
+     * The single choke-point every literal string in an OBJECT goes through - a field's `/T` and `/V`, a
+     * bookmark `/Title`, a link `/URI`, an `/Alt` text, a destination name.
+     *
+     * Without a security handler this is the escaped literal we have always written, so output stays
+     * byte-identical. With one, the raw bytes are registered for the finalize pass and a placeholder takes
+     * their place: ISO 32000-1 7.6.2 requires ALL strings and streams to be encrypted, and the ones missed
+     * here were exactly the values a password is supposed to protect (ISSUE-7).
+     *
+     * A string INSIDE a content stream needs none of this - the stream is enciphered as a whole.
+     */
+    pdfString(text: string): string;
     private streamPayload;
     private stream;
     addContentStream(content: string): number;
+    addFormXObject(bbox: string, content: string, resources?: string): number;
     changePDFConfig(config: PDFConfig): void;
     getPDFConfig(): PDFConfig;
     private fillConfigWithStandardValues;

package/dist/utils/pdf-object-manager.js

@@ -11,6 +11,7 @@ import { isEmojiCodePoint } from "../text/emoji-codepoints.js";
 import { StructTree } from "./struct-tree.js";
 import { OutlineBuilder } from "./outline.js";
 import { DestRegistry } from "./dest-registry.js";
+import { AcroFormCollector } from "../forms/acroform.js";
 // Enums come from the leaf config module (never in a cycle); the config type is
 // erased at runtime so it can come from the cyclic module safely.
 import { ColorMode, Orientation } from "../renderer/pdf-config.js";
@@ -134,6 +135,9 @@ export class PDFObjectManager {
     get dests() {
         return this._dests;
     }
+    get acroform() {
+        return this._acroform;
+    }
     constructor(pageSize) {
         this.objects = [];
         this.objectPositions = [];
@@ -167,6 +171,7 @@ export class PDFObjectManager {
         this.compress = false;
         this.overflowPolicy = "error";
         this.encJobs = [];
+        this.strJobs = [];
         // Accessible (PDF/UA) tagging, off by default (byte-identical output); the API turns it on.
         this._struct = new StructTree();
         // Document outline (bookmarks). Empty unless a `Bookmark` was placed; then finalize() emits /Outlines.
@@ -174,6 +179,9 @@ export class PDFObjectManager {
         // Named destinations (internal-link jump targets). Empty unless an `Anchor` was placed; then it emits
         // a /Names /Dests tree.
         this._dests = new DestRegistry();
+        // Interactive form fields (AcroForm). Empty unless a form field was placed; then finalize() emits the
+        // catalog /AcroForm dict and each field's widget lands in its page /Annots.
+        this._acroform = new AcroFormCollector();
         // Whether to kern. Document-level: measuring (via `runAdvance`, which reads this off the metrics)
         // and drawing (the backend emits a `TJ`) both consult it, so they can never disagree. OFF while the
         // embedded-font path (kern/GPOS) is unbuilt - a standard-14-only kerning would set the 14 system
@@ -213,6 +221,32 @@ export class PDFObjectManager {
     encToken(id) {
         return `
JENC:${id}
`;
     }
+    // The same trick for a literal STRING. A separate marker because the two are swapped differently: a
+    // stream keeps its delimiters and only the payload changes, a string is replaced whole by a hex one.
+    strToken(id) {
+        return `\x00\x02JSTR:${id}\x02\x00`;
+    }
+    /**
+     * The single choke-point every literal string in an OBJECT goes through - a field's `/T` and `/V`, a
+     * bookmark `/Title`, a link `/URI`, an `/Alt` text, a destination name.
+     *
+     * Without a security handler this is the escaped literal we have always written, so output stays
+     * byte-identical. With one, the raw bytes are registered for the finalize pass and a placeholder takes
+     * their place: ISO 32000-1 7.6.2 requires ALL strings and streams to be encrypted, and the ones missed
+     * here were exactly the values a password is supposed to protect (ISSUE-7).
+     *
+     * A string INSIDE a content stream needs none of this - the stream is enciphered as a whole.
+     */
+    pdfString(text) {
+        if (!this.security) {
+            return `(${text.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)")})`;
+        }
+        // Encrypt the bytes the unencrypted path would have written, so a viewer decrypts to the same value.
+        // No escaping is applied: the result is emitted as a HEX string, which has no escapes to get wrong.
+        const bytes = new Uint8Array(getArrayBuffer(text));
+        const id = this.strJobs.push(bytes) - 1;
+        return this.strToken(id);
+    }
     // The single encryption choke-point every stream emitter routes through (stream(), registerImage). Without
     // a security handler: the bytes as a latin1 string + their length. With one: register the raw bytes for the
     // finalize pass and return a placeholder + the pre-computable encrypted length (16-byte IV + PKCS#7 padding).
@@ -246,6 +280,14 @@ export class PDFObjectManager {
     addContentStream(content) {
         return this.addObject(this.stream("", new Uint8Array(getArrayBuffer(content))));
     }
+    // A Form XObject: a self-contained content stream with its own /BBox (+ optional /Resources). Used for
+    // form-field appearance streams (/AP). Routes through the same choke-point as page content, so
+    // compression and encryption apply. Returns the object number.
+    addFormXObject(bbox, content, resources) {
+        const dict = `/Type /XObject /Subtype /Form /BBox ${bbox}` +
+            (resources ? ` /Resources << ${resources} >>` : "");
+        return this.addObject(this.stream(dict, new Uint8Array(getArrayBuffer(content))));
+    }
     changePDFConfig(config) {
         this.pdfConfig = { ...this.pdfConfig, ...config };
     }
@@ -327,9 +369,8 @@ endstream`;
     attachFile(name, data, opts = {}) {
         const subtype = (opts.mimeType ?? "application/octet-stream").replace(/\//g, "#2F");
         const embedded = this.addObject(this.stream(`/Type /EmbeddedFile /Subtype /${subtype} /Params << /Size ${data.length} >>`, data));
-        const escaped = (s) => s.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
-        const desc = opts.description ? ` /Desc (${escaped(opts.description)})` : "";
-        const filespec = this.addObject(`<< /Type /Filespec /F (${escaped(name)}) /UF (${escaped(name)}) ` +
+        const desc = opts.description ? ` /Desc ${this.pdfString(opts.description)}` : "";
+        const filespec = this.addObject(`<< /Type /Filespec /F ${this.pdfString(name)} /UF ${this.pdfString(name)} ` +
             `/AFRelationship /${opts.relationship ?? "Unspecified"}${desc} ` +
             `/EF << /F ${embedded} 0 R /UF ${embedded} 0 R >> >>`);
         this.attachments.push({ name, filespec });
@@ -350,8 +391,8 @@ endstream`;
     setOutputIntent(icc, opts = {}) {
         const profile = this.addObject(this.stream("/N 3", icc));
         this.outputIntent = this.addObject(`<< /Type /OutputIntent /S /GTS_PDFA1 ` +
-            `/OutputConditionIdentifier (${opts.identifier ?? "sRGB"}) ` +
-            `/Info (${opts.info ?? "sRGB IEC61966-2.1"}) /DestOutputProfile ${profile} 0 R >>`);
+            `/OutputConditionIdentifier ${this.pdfString(opts.identifier ?? "sRGB")} ` +
+            `/Info ${this.pdfString(opts.info ?? "sRGB IEC61966-2.1")} /DestOutputProfile ${profile} 0 R >>`);
     }
     getOutputIntent() {
         return this.outputIntent;
@@ -399,6 +440,18 @@ endstream`;
             if (idx >= 0)
                 this.objects[idx] = this.objects[idx].replace(token, () => ciphertext);
         }
+        // Strings: the same idea, but a string is replaced WHOLE - `(text)` becomes `<ciphertext>`. Hex,
+        // because the ciphertext is binary and a hex string has no escape rules to get wrong.
+        for (let id = 0; id < this.strJobs.length; id++) {
+            const cipher = await this.security.encrypt(this.strJobs[id]);
+            const hex = Array.from(cipher, (b) => b.toString(16).padStart(2, "0").toUpperCase()).join("");
+            const token = this.strToken(id);
+            const idx = this.objects.findIndex((o) => o.includes(token));
+            if (idx >= 0)
+                this.objects[idx] = this.objects[idx].replace(token, () => `<${hex}>`);
+        }
+        // Added LAST on purpose: the /Encrypt dictionary's own strings must stay in the clear (7.6.2), and
+        // they would otherwise be swept up by the pass above.
         this.encryptObjNum = this.addObject(`<< ${this.security.encryptDict()} >>`);
     }
     // Registers (or reuses) a transparency graphics state and returns its resource name
@@ -673,7 +726,7 @@ endstream`;
             .map((g) => `${g} [${all[g] ?? 1000}]`)
             .join(" ");
         return (`<< /Type /Font /Subtype /CIDFontType2 /BaseFont /${pdfName(name)} ` +
-            `/CIDSystemInfo << /Registry (Adobe) /Ordering (Identity) /Supplement 0 >> ` +
+            `/CIDSystemInfo << /Registry ${this.pdfString("Adobe")} /Ordering ${this.pdfString("Identity")} /Supplement 0 >> ` +
             `/FontDescriptor ${descriptor} 0 R /CIDToGIDMap /Identity ` +
             `/DW 1000 /W [${w}] >>`);
     }

package/dist/utils/struct-tree.js

@@ -1,5 +1,4 @@
 // Escapes a PDF literal string ( ... ) - the language tag is safe ASCII, but /Alt can carry arbitrary text.
-const esc = (s) => s.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
 // A structure role reaches the PDF as a raw name (/H1, /S /Table). Roles come from a controlled set,
 // but restrict them to a safe PDF-name token anyway (defence-in-depth) so a stray "/", whitespace, or
 // operator can never corrupt the content stream / object dictionary. Empty after stripping -> /Span.
@@ -90,7 +89,7 @@ export class StructTree {
                 ...childrenOf(e.key).map((c) => `${objNum.get(c.key)} 0 R`),
                 ...e.mc.map((m) => `<< /Type /MCR /Pg ${pg(m.structParents)} 0 R /MCID ${m.mcid} >>`),
             ].join(" ");
-            const alt = e.alt ? ` /Alt (${esc(e.alt)})` : "";
+            const alt = e.alt ? ` /Alt ${om.pdfString(e.alt)}` : "";
             // PDF/UA 7.5: a header cell needs a Scope so a reader can associate data cells with it. Our headers
             // are a header ROW (the Table `header` option), so each TH is the head of its Column.
             const attr = e.role === "TH" ? " /A << /O /Table /Scope /Column >>" : "";
@@ -125,6 +124,6 @@ export class StructTree {
         om.replaceObject(parentTreeNum, `<< /Nums [ ${nums.join(" ")} ] >>`);
         om.replaceObject(rootNum, `<< /Type /StructTreeRoot /K ${docNum} 0 R /ParentTree ${parentTreeNum} 0 R ` +
             `/ParentTreeNextKey ${this.structParentsCounter} >>`);
-        return `/MarkInfo << /Marked true >> /StructTreeRoot ${rootNum} 0 R /Lang (${esc(this.lang)})`;
+        return `/MarkInfo << /Marked true >> /StructTreeRoot ${rootNum} 0 R /Lang ${om.pdfString(this.lang)}`;
     }
 }

package/dist/validators/element-validator.js

@@ -41,9 +41,13 @@ export class Validator {
         }
     }
     static validateFlexElement(element) {
-        // Ensure flexible elements have valid flex values
-        if (element.getFlex() <= 0) {
-            throw new Error(`Flexible element ${element.constructor.name} has invalid flex value`);
+        // Ensure flexible elements have valid flex values. The message names what the CALLER wrote, not the
+        // element class: `Spacer` and `Expanded` are what exists in their document, `ExpandedElement` is not.
+        const flex = element.getFlex();
+        if (flex <= 0) {
+            throw new Error(`@jasy/pdf: Spacer/Expanded needs a flex above 0, got ${flex}. Flex is a SHARE of the leftover ` +
+                "space, so 0 would claim none - which is what leaving the element out does. For a fixed gap " +
+                "use the `gap` of the surrounding Column or Row, or a Box with a height.");
         }
         // Ensure a flexible element does not contain another flexible element
         if (hasChildProp(element)) {

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@jasy/pdf",
-  "version": "1.0.0-alpha.7",
+  "version": "1.0.0-alpha.8",
   "description": "Declarative, component-based PDF generation in pure TypeScript - Flutter-style components, real AFM font metrics, a hand-rolled PDF writer. No headless browser, no Java.",
   "keywords": [
     "declarative",
+    "e-invoice",
     "factur-x",
     "invoice",
     "layout",
@@ -12,6 +13,7 @@
     "pdf-a",
     "pdf-generation",
     "typescript",
+    "xrechnung",
     "zugferd"
   ],
   "license": "MIT",
@@ -30,7 +32,12 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./edit": {
+      "types": "./dist/edit/index.d.ts",
+      "default": "./dist/edit/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "dependencies": {
     "fflate": "^0.8.3",