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

package/dist/elements/text-element.js

@@ -4,12 +4,31 @@
 // breaks the constructor-keyed RendererRegistry. A direct import keeps the graph acyclic.
 import { TextRenderer } from "../renderer/text-renderer.js";
 import { DEFAULT_TEXT_STYLE } from "../text/text-style.js";
-import { wrapStringIntoLines, breakSegmentsIntoLines, segmentLinesToSegments, } from "../text/line-breaker.js";
+import { applyTextTransform } from "../text/text-style.js";
+import { splitByFont } from "../text/font-fallback.js";
+import { singleLineWidth, MAX_SPACE_SHRINK, wrapStringIntoLines, breakSegmentsIntoLines, segmentLinesToSegments, } from "../text/line-breaker.js";
+import { adjustForOrphansWidows, DEFAULT_ORPHANS, DEFAULT_WIDOWS, } from "../text/orphans-widows.js";
 import { lineBoxForSegmentLine, lineBoxForString } from "../text/line-metrics.js";
-import { runAdvance } from "../text/advance.js";
-import { SizedPDFElement } from "./pdf-element.js";
+import { HorizontalAlignment, SizedPDFElement } from "./pdf-element.js";
+/** How far a run sits off the baseline, as a fraction of its font size (up is positive). */
+export const VERTICAL_TEXT_SHIFT = {
+    baseline: 0,
+    super: 1 / 3,
+    sub: -1 / 5,
+};
+/**
+ * A measurement in points has to be a real number. A NaN or an Infinity would travel all the way into
+ * the content stream as a position - the backend refuses it there, but by then the message names a
+ * coordinate rather than the property that was wrong. Rejected here, where the caller can see it.
+ */
+function finitePoints(value, name) {
+    if (value !== undefined && !Number.isFinite(value)) {
+        throw new Error(`@jasy/pdf: Invalid ${name} ${value}: it must be a finite number of points.`);
+    }
+    return value;
+}
 export class TextElement extends SizedPDFElement {
-    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, overflow = "clip", lineHeight, underline, strikethrough, skipInk, letterSpacing, role, }) {
+    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, orphans, widows, overflow = "clip", lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, fontFallback, textTransform, wordSpacing, textIndent, role, }) {
         super({ x: 0, y: 0 });
         this.role = role;
         this.rawFontSize = fontSize;
@@ -22,8 +41,15 @@ export class TextElement extends SizedPDFElement {
         this.rawStrikethrough = strikethrough;
         this.rawSkipInk = skipInk;
         this.rawLetterSpacing = letterSpacing;
+        this.rawDirection = direction;
+        this.rawFontFallback = fontFallback;
+        this.rawTextTransform = textTransform;
+        this.rawWordSpacing = finitePoints(wordSpacing, "wordSpacing");
+        this.rawTextIndent = finitePoints(textIndent, "textIndent");
         this.content = content;
         this.maxLines = maxLines;
+        this.orphans = orphans;
+        this.widows = widows;
         this.overflow = overflow;
         this.applyStyle(DEFAULT_TEXT_STYLE);
     }
@@ -31,6 +57,57 @@ export class TextElement extends SizedPDFElement {
     resolveStyle(ctx) {
         this.applyStyle(ctx.textStyle ?? DEFAULT_TEXT_STYLE);
     }
+    /** Justified lines may be squeezed to keep a word; every other alignment gets no slack. Read by the
+     *  breaker in BOTH passes, or a measured line and a drawn one would disagree about where it ends. */
+    /**
+     * The content as it is measured AND drawn - `text-transform` applied. One place, so a recased
+     * paragraph can never be measured in one casing and drawn in another (`ABC` and `abc` are not the
+     * same width in most fonts).
+     */
+    display(metrics) {
+        const cased = this.recased();
+        // A SPAN may bring its own stack, so the element's being empty is not enough to skip the pass.
+        const anyStack = this.fontFallback.length > 0 ||
+            (typeof cased !== "string" && cased.some((seg) => (seg.fontFallback?.length ?? 0) > 0));
+        if (!anyStack || !metrics)
+            return cased;
+        // Font fallback turns the content into spans - one per family - which every later pass already
+        // knows how to handle. Nothing new downstream.
+        const pieces = typeof cased === "string" ? [{ content: cased }] : cased;
+        const out = [];
+        for (const seg of pieces) {
+            const runs = splitByFont(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontFallback ?? this.fontFallback, seg.fontStyle ?? this.fontStyle, metrics);
+            if (!runs)
+                out.push(seg);
+            else
+                for (const run of runs)
+                    out.push({ ...seg, content: run.text, fontFamily: run.fontFamily });
+        }
+        return out;
+    }
+    /** The content with `text-transform` applied, and nothing else. */
+    recased() {
+        if (this.textTransform === "none")
+            return this.content;
+        if (typeof this.content === "string") {
+            return applyTextTransform(this.content, this.textTransform).text;
+        }
+        // The capitalisation state runs THROUGH the spans: `span("hel") + span("lo")` is one word.
+        let atWordStart = true;
+        return this.content.map((seg) => {
+            const done = applyTextTransform(seg.content, this.textTransform, atWordStart);
+            atWordStart = done.atWordStart;
+            return { ...seg, content: done.text };
+        });
+    }
+    lineOptions() {
+        return {
+            wordSpacing: this.wordSpacing,
+            indent: this.textIndent,
+            // Justified lines may be squeezed to keep a word; every other alignment gets no slack.
+            shrink: this.textAlignment === HorizontalAlignment.justify ? MAX_SPACE_SHRINK : 0,
+        };
+    }
     applyStyle(ts) {
         this.fontSize = this.rawFontSize ?? ts.fontSize;
         this.fontFamily = this.rawFontFamily ?? ts.fontFamily;
@@ -42,6 +119,11 @@ export class TextElement extends SizedPDFElement {
         this.strikethrough = this.rawStrikethrough ?? ts.strikethrough;
         this.skipInk = this.rawSkipInk ?? ts.skipInk;
         this.letterSpacing = this.rawLetterSpacing ?? ts.letterSpacing;
+        this.direction = this.rawDirection ?? ts.direction;
+        this.fontFallback = this.rawFontFallback ?? ts.fontFallback;
+        this.textTransform = this.rawTextTransform ?? ts.textTransform;
+        this.wordSpacing = this.rawWordSpacing ?? ts.wordSpacing;
+        this.textIndent = this.rawTextIndent ?? ts.textIndent;
     }
     /**
      * Splits the paragraph at line boxes (Slice 1). The lines that fit in `maxHeight` stay;
@@ -51,23 +133,25 @@ export class TextElement extends SizedPDFElement {
      */
     fragment(maxHeight, width, ctx) {
         this.resolveStyle(ctx);
-        return typeof this.content === "string"
-            ? this.fragmentString(this.content, maxHeight, width, ctx)
-            : this.fragmentSegments(this.content, maxHeight, width, ctx);
+        const content = this.display(ctx.metrics);
+        return typeof content === "string"
+            ? this.fragmentString(content, maxHeight, width, ctx)
+            : this.fragmentSegments(content, maxHeight, width, ctx);
     }
     // Plain string: every wrapped line gets the same box (the same one calculateTextHeight uses),
     // so `floor(maxHeight / lineBox)` lines fit.
     fragmentString(content, maxHeight, width, ctx) {
-        const lines = wrapStringIntoLines(content, this.fontFamily, this.fontSize, this.fontStyle, width, ctx.metrics, this.maxLines, this.overflow, this.letterSpacing);
+        const lines = wrapStringIntoLines(content, this.fontFamily, this.fontSize, this.fontStyle, width, ctx.metrics, this.maxLines, this.overflow, this.letterSpacing, this.lineOptions());
         const box = lineBoxForString(ctx.metrics, this.fontFamily, this.fontStyle, this.fontSize, this.lineHeight);
-        const fittedLineCount = Math.floor(maxHeight / box.height);
+        const fittedLineCount = adjustForOrphansWidows(Math.floor(maxHeight / box.height), lines.length, this.breakRule());
         if (fittedLineCount <= 0)
             return { fitted: null, remainder: this };
         if (fittedLineCount >= lines.length)
             return { fitted: this, remainder: null };
         return {
             fitted: this.cloneWithContent(lines.slice(0, fittedLineCount).join(" ")),
-            remainder: this.cloneWithContent(lines.slice(fittedLineCount).join(" ")),
+            // A continuation is no longer the paragraph's FIRST line, so it carries no indent.
+            remainder: this.cloneWithContent(lines.slice(fittedLineCount).join(" "), 0),
         };
     }
     // Styled segments: each line's height comes from the fonts on it, so pack lines by cumulative
@@ -78,29 +162,40 @@ export class TextElement extends SizedPDFElement {
             fontSize: this.fontSize,
             fontStyle: this.fontStyle,
             letterSpacing: this.letterSpacing,
+            direction: this.direction,
+            wordSpacing: this.wordSpacing,
+            textIndent: this.textIndent,
         };
         const lines = breakSegmentsIntoLines(content, defaults, width, ctx.metrics, this.maxLines, this.overflow);
         let used = 0;
-        let fittedLineCount = 0;
+        let packed = 0;
         for (const line of lines) {
             const lineBox = lineBoxForSegmentLine(line, defaults, ctx.metrics, this.lineHeight).height;
             if (used + lineBox > maxHeight)
                 break;
             used += lineBox;
-            fittedLineCount++;
+            packed++;
         }
+        const fittedLineCount = adjustForOrphansWidows(packed, lines.length, this.breakRule());
         if (fittedLineCount <= 0)
             return { fitted: null, remainder: this };
         if (fittedLineCount >= lines.length)
             return { fitted: this, remainder: null };
         return {
             fitted: this.cloneWithContent(segmentLinesToSegments(lines.slice(0, fittedLineCount))),
-            remainder: this.cloneWithContent(segmentLinesToSegments(lines.slice(fittedLineCount))),
+            remainder: this.cloneWithContent(segmentLinesToSegments(lines.slice(fittedLineCount)), 0),
+        };
+    }
+    /** The orphan/widow minimums for this paragraph; unset means the CSS default of 2 lines each. */
+    breakRule() {
+        return {
+            orphans: this.orphans ?? DEFAULT_ORPHANS,
+            widows: this.widows ?? DEFAULT_WIDOWS,
         };
     }
     // A copy carrying the same style but different (already-wrapped) content. Re-wrapping at
     // the same width reproduces exactly those lines (greedy is deterministic).
-    cloneWithContent(content) {
+    cloneWithContent(content, indent = this.textIndent) {
         return new TextElement({
             content,
             fontSize: this.fontSize,
@@ -109,12 +204,17 @@ export class TextElement extends SizedPDFElement {
             color: this.color,
             textAlignment: this.textAlignment,
             maxLines: this.maxLines,
+            orphans: this.orphans,
+            widows: this.widows,
             overflow: this.overflow,
             lineHeight: this.lineHeight,
             underline: this.underline,
             strikethrough: this.strikethrough,
             skipInk: this.skipInk,
             letterSpacing: this.letterSpacing,
+            direction: this.direction,
+            wordSpacing: this.wordSpacing,
+            textIndent: indent,
             role: this.role,
         }).adoptStructId(this); // a wrapped remainder is the SAME logical paragraph (one P across pages)
     }
@@ -125,11 +225,12 @@ export class TextElement extends SizedPDFElement {
         // Bounded width (e.g. inside a Column) wraps to that width; an unbounded width
         // (e.g. inside a Row) means the text takes its natural single-line width and does
         // not wrap. Columns always bound the width, so this leaves their layout untouched.
+        this.resolved = this.display(ctx.metrics);
         this.width = constraints.hasBoundedWidth
             ? constraints.maxWidth
             : this.naturalWidth(ctx.metrics);
         const wrapWidth = this.width ?? 0;
-        this.height = TextRenderer.calculateTextHeight(this.content, this.fontSize, this.fontFamily, this.fontStyle, ctx.metrics, wrapWidth, this.maxLines, this.overflow, this.lineHeight, this.letterSpacing);
+        this.height = TextRenderer.calculateTextHeight(this.resolved, this.fontSize, this.fontFamily, this.fontStyle, ctx.metrics, wrapWidth, this.maxLines, this.overflow, this.lineHeight, this.letterSpacing, this.lineOptions());
         // Top-left coordinates (y = top of the text box). The baseline offset and the
         // Y-flip are applied downstream (the line-builder positions baselines, the seam
         // flips to PDF), so the element stays coordinate-system-blind.
@@ -144,24 +245,17 @@ export class TextElement extends SizedPDFElement {
      *  - enough to tip a borderline string (e.g. "20 Jun 2026", wider than "04 Jul 2026" only because
      *  'n' beats 'l') one bit over its own width, dropping the last word onto a second line. */
     naturalWidth(metrics) {
-        const oneLine = (text, family, size, style, letterSpacing) => {
-            const font = { fontFamily: family, fontSize: size, fontStyle: style };
-            const words = text.split(" ");
-            const space = runAdvance(metrics, " ", font, letterSpacing);
-            let width = 0;
-            words.forEach((word, i) => {
-                const w = runAdvance(metrics, word, font, letterSpacing);
-                // Group (word + space) as one term, exactly like the breaker - see the note above. Both use
-                // the same `runAdvance`, so the two agree bit for bit even with letterSpacing.
-                width += i < words.length - 1 ? w + space : w;
-            });
-            return width;
-        };
-        if (typeof this.content === "string") {
-            return oneLine(this.content, this.fontFamily, this.fontSize, this.fontStyle, this.letterSpacing);
+        // The breaker's own sum, to the last bit - see `singleLineWidth`.
+        const oneLine = (text, family, size, style, letterSpacing) => singleLineWidth(text, { fontFamily: family, fontSize: size, fontStyle: style }, metrics, letterSpacing, this.wordSpacing);
+        // The FIRST line starts `textIndent` in, so an unbounded box has to be that much wider.
+        const indent = Math.max(0, this.textIndent);
+        const content = this.display(metrics);
+        if (typeof content === "string") {
+            return (indent +
+                oneLine(content, this.fontFamily, this.fontSize, this.fontStyle, this.letterSpacing));
         }
-        return this.content.reduce((sum, seg) => sum +
-            oneLine(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontSize ?? this.fontSize, seg.fontStyle ?? this.fontStyle, seg.letterSpacing ?? this.letterSpacing), 0);
+        return content.reduce((sum, seg) => sum +
+            oneLine(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontSize ?? this.fontSize, seg.fontStyle ?? this.fontStyle, seg.letterSpacing ?? this.letterSpacing), indent);
     }
     getProps() {
         return {
@@ -173,15 +267,20 @@ export class TextElement extends SizedPDFElement {
             fontFamily: this.fontFamily,
             fontStyle: this.fontStyle,
             color: this.color,
-            content: this.content,
+            content: this.resolved ?? this.content,
             textAlignment: this.textAlignment,
             maxLines: this.maxLines,
+            orphans: this.orphans,
+            widows: this.widows,
             overflow: this.overflow,
             lineHeight: this.lineHeight,
             underline: this.underline,
             strikethrough: this.strikethrough,
             skipInk: this.skipInk,
             letterSpacing: this.letterSpacing,
+            direction: this.direction,
+            wordSpacing: this.wordSpacing,
+            textIndent: this.textIndent,
             role: this.role,
         };
     }

package/dist/forms/acroform.d.ts

@@ -0,0 +1,63 @@
+import type { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import type { FormFieldNode } from "../ir/display-list.js";
+/**
+ * Collects the document's form fields as pages render, then emits the catalog `/AcroForm` dictionary at
+ * finalize. Mirrors `OutlineBuilder` / `DestRegistry`: a no-op returning "" when no field was placed, so
+ * a document without a form stays byte-identical.
+ */
+export declare class AcroFormCollector {
+    private fieldRefs;
+    private radioGroups;
+    private needAppearances;
+    private helvNum?;
+    private zadbNum?;
+    private hasSignature;
+    private usedNames;
+    private bake;
+    /** Turn appearance baking off (`renderToBytes(doc, { fieldAppearances: false })`). */
+    setBakeAppearances(on: boolean): void;
+    /** The size to draw a value at. A field may ask for `0` - the PDF convention for "auto-size"; we then
+     *  fit the capitals comfortably inside the box, which is what a viewer's auto-size does. */
+    private drawSize;
+    /** Measure one line for the appearance generator. */
+    private line;
+    /** Bake a text field's value into an appearance stream; returns the XObject number. */
+    private bakeText;
+    /** Bake a choice field: a combo shows its current value on one line, a list box shows its options
+     *  with the selected rows highlighted. */
+    private bakeChoice;
+    get isEmpty(): boolean;
+    private helv;
+    /**
+     * ZapfDingbats, the font a check mark lives in. Needed even though we bake the appearance ourselves:
+     * a viewer told to regenerate (`/NeedAppearances`, which filling a form sets) redraws a check box from
+     * its `/DA`, and the conventional `/DA` for one names `/ZaDb`. Without the matching `/DR` entry the
+     * viewer cannot resolve the font - poppler says "Unknown font tag 'ZaDb'" and draws no check at all.
+     * No encoding: ZapfDingbats brings its own.
+     */
+    private zadb;
+    /**
+     * A field name is its identity: two fields sharing one are ONE field to every viewer, showing the same
+     * value in both places and overwriting each other as the reader types. The format allows it and says
+     * nothing, so the mistake surfaces only when someone fills the form. Named here instead.
+     *
+     * A radio GROUP is the exception - its buttons deliberately share a name, which is what makes them
+     * mutually exclusive - so it never comes through here.
+     */
+    private claimName;
+    /** Emit the widget object for one form-field IR node, register it as a field, and return its object
+     *  number so the PageRenderer can add it to that page's /Annots. */
+    addField(node: FormFieldNode, om: PDFObjectManager): number;
+    /** A push button (/Btn, Pushbutton flag): no value, an optional action, and a baked caption. The
+     *  caption is measured here (the appearance module stays free of font metrics) and drawn into an
+     *  appearance stream that carries its own font resource. */
+    private buildPushButtonWidget;
+    /** A radio button: one KID widget of its group's shared field. The group field is reserved on first
+     *  sight (and added to /Fields); each button adds itself to that field's /Kids. Returns the kid widget
+     *  number, which goes into the PAGE /Annots (the parent field does not). */
+    private addRadio;
+    /** A signature field (/Sig): an EMPTY placeholder with a baked "sign here" face. No /V - an unsigned
+     *  field has no value; a signing tool fills that in (and replaces this appearance) later. */
+    private buildSignatureWidget;
+    finalize(om: PDFObjectManager): string;
+}