@jasy/pdf 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/elements/text-element.js

@@ -1,18 +1,17 @@
-// Import the renderer DIRECTLY, not via the "../renderer" barrel: the barrel pulls in
-// pdf-renderer (and every element) while this element module is still loading, which under
-// ESM (Vite/vitest, and the future framework bindings) duplicates the element classes and
-// 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 { BoxConstraints } from "../layout/box-constraints.js";
 import { applyTextTransform } from "../text/text-style.js";
 import { splitByFont } from "../text/font-fallback.js";
 import { runAdvance } from "../text/advance.js";
-import { singleLineWidth, MAX_SPACE_SHRINK, wrapStringIntoLines, breakSegmentsIntoLines, segmentLinesToSegments, } from "../text/line-breaker.js";
+import { runStyleOf, singleLineWidth, MAX_SPACE_SHRINK, breakSegmentsIntoLines, } from "../text/line-breaker.js";
+import { hyphenPieces } from "../text/hyphen-breaks.js";
 import { adjustForOrphansWidows, DEFAULT_ORPHANS, DEFAULT_WIDOWS, } from "../text/orphans-widows.js";
-import { lineBoxForSegmentLine, lineBoxForString } from "../text/line-metrics.js";
+import { lineBoxForSegmentLine, linesHeight } from "../text/line-metrics.js";
 import { HorizontalAlignment, SizedPDFElement } from "./pdf-element.js";
 import { normalizeContent } from "../text/whitespace.js";
 import { coverText } from "../text/glyph-coverage.js";
+import { diagnose, pageOf } from "../common/diagnostics.js";
+import { BuiltFromContext } from "../layout/layout-cache.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,
@@ -31,9 +30,15 @@ function finitePoints(value, name) {
     return value;
 }
 export class TextElement extends SizedPDFElement {
-    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, orphans, widows, overflow = "clip", lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, fontFallback, textTransform, wordSpacing, textIndent, breakWord, hyphenate, ligatures, role, }) {
+    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, orphans, widows, overflow = "clip", lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, fontFallback, textTransform, wordSpacing, textIndent, breakWord, hyphenate, ligatures, role, shownLines, }) {
         super({ x: 0, y: 0 });
+        this.broken = new BuiltFromContext(() => false);
+        /** What `covered` had to remove, reported where the text is laid out on its page (see
+         *  `calculateLayout`). A split paragraph's first piece carries its parent's, as `lostBefore`. */
+        this.lostGlyphs = [];
+        this.lostBefore = [];
         this.role = role;
+        this.shownLines = shownLines;
         this.rawFontSize = fontSize;
         this.rawFontFamily = fontFamily;
         this.rawFontStyle = fontStyle;
@@ -86,8 +91,7 @@ export class TextElement extends SizedPDFElement {
             return memo.value;
         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));
+        const anyStack = this.fontFallback.length > 0 || cased.some((seg) => (seg.fontFallback?.length ?? 0) > 0);
         if (!metrics)
             return cased;
         const remember = (value) => {
@@ -104,11 +108,9 @@ export class TextElement extends SizedPDFElement {
         };
         if (!anyStack)
             return remember(this.covered(cased, metrics));
-        // 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;
+        // Font fallback splits a span into more spans - one per family. Nothing new downstream.
         const out = [];
-        for (const seg of pieces) {
+        for (const seg of cased) {
             const runs = splitByFont(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontFallback ?? this.fontFallback, seg.fontStyle ?? this.fontStyle, metrics);
             if (!runs)
                 out.push(seg);
@@ -125,33 +127,30 @@ export class TextElement extends SizedPDFElement {
      * back unchanged, so an ordinary document is byte-identical.
      */
     covered(content, metrics) {
-        const report = (dropped) => metrics.reportMissingGlyph?.(dropped);
-        if (typeof content === "string") {
-            const { text, dropped } = coverText(content, this.fontFamily, this.fontStyle, metrics);
-            if (dropped.length > 0)
-                report(dropped);
-            return text;
-        }
-        return content.map((seg) => {
+        // Collected over every span: the element is reported once, with everything it lost, on the page it
+        // is laid out on - not here, which may be measuring it for an earlier page.
+        const lost = [];
+        const covered = content.map((seg) => {
             const { text, dropped } = coverText(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontStyle ?? this.fontStyle, metrics);
-            if (dropped.length > 0)
-                report(dropped);
+            lost.push(...dropped);
             return text === seg.content ? seg : { ...seg, content: text };
         });
+        this.lostGlyphs = [...new Set(lost)];
+        return covered;
     }
-    /** The content with `text-transform` applied, and nothing else. */
+    /** The content as spans, 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;
-        }
+        // A string is one span: from here on, measuring, breaking and drawing know only spans.
+        const spans = typeof this.content === "string" ? [{ content: this.content }] : this.content;
+        const transformOf = (seg) => seg.textTransform ?? this.textTransform;
+        if (spans.every((seg) => transformOf(seg) === "none"))
+            return spans;
         // 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);
+        return spans.map((seg) => {
+            const done = applyTextTransform(seg.content, transformOf(seg), atWordStart);
             atWordStart = done.atWordStart;
-            return { ...seg, content: done.text };
+            return done.text === seg.content ? seg : { ...seg, content: done.text };
         });
     }
     lineOptions() {
@@ -162,6 +161,7 @@ export class TextElement extends SizedPDFElement {
             ligatures: this.ligatures,
             // Justified lines may be squeezed to keep a word; every other alignment gets no slack.
             shrink: this.textAlignment === HorizontalAlignment.justify ? MAX_SPACE_SHRINK : 0,
+            shownLines: this.shownLines,
         };
     }
     applyStyle(ts) {
@@ -188,44 +188,16 @@ export class TextElement extends SizedPDFElement {
      * Splits the paragraph at line boxes (Slice 1). The lines that fit in `maxHeight` stay;
      * the rest become a remainder `TextElement` re-wrapped on the next page. If not even one
      * line fits, nothing is forced here - the caller (the container) decides whether to move
-     * the whole element on for progress. Handles both plain strings and styled segments.
+     * the whole element on for progress.
      */
     fragment(maxHeight, width, ctx) {
         this.resolveStyle(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, this.lineOptions());
-        const box = lineBoxForString(ctx.metrics, this.fontFamily, this.fontStyle, this.fontSize, this.lineHeight);
-        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(" ")),
-            // 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
-    // box height. Rebuild the fitted/remainder halves back into TextSegment[].
-    fragmentSegments(content, maxHeight, width, ctx) {
-        const defaults = {
-            fontFamily: this.fontFamily,
-            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);
+        // The SAME knobs measuring and drawing break with (`textHeight`, the renderer), or this
+        // would cut a paragraph at a line count it is never drawn with. Each line's height comes from
+        // the fonts on it, so lines are packed by their cumulative height.
+        const defaults = this.segmentDefaults();
+        const lines = this.linesAt(width, ctx);
         let used = 0;
         let packed = 0;
         for (const line of lines) {
@@ -240,9 +212,35 @@ export class TextElement extends SizedPDFElement {
             return { fitted: null, remainder: this };
         if (fittedLineCount >= lines.length)
             return { fitted: this, remainder: null };
+        // A piece is a window onto the SAME text, not the lines glued back together: the first page draws
+        // the first lines of the whole paragraph (broken exactly as here, same text, same width), and the
+        // next one continues from where its first line starts in the source - inside its span, keeping
+        // that span's style. Hard breaks, a word split over the break and the justified last line on the
+        // page all survive that way. A continuation is no longer the paragraph's FIRST line, so it
+        // carries no indent; whatever is left of a line cap goes with it.
+        const { segment, offset } = lines[fittedLineCount].start;
+        const rest = [
+            { ...content[segment], content: content[segment].content.slice(offset) },
+            ...content.slice(segment + 1),
+        ];
+        const fitted = this.cloneWithContent(content, this.textIndent, { shownLines: fittedLineCount });
+        // The piece is cut from already-covered text, so it would find nothing missing itself.
+        fitted.lostBefore = [...this.lostBefore, ...this.lostGlyphs];
+        return {
+            fitted,
+            remainder: this.cloneWithContent(rest, 0, {
+                maxLines: this.maxLines === undefined ? undefined : this.maxLines - fittedLineCount,
+            }),
+        };
+    }
+    /** How the text is broken: the knobs `textHeight` and the renderer pass too. */
+    segmentDefaults() {
         return {
-            fitted: this.cloneWithContent(segmentLinesToSegments(lines.slice(0, fittedLineCount))),
-            remainder: this.cloneWithContent(segmentLinesToSegments(lines.slice(fittedLineCount)), 0),
+            fontFamily: this.fontFamily,
+            fontSize: this.fontSize,
+            fontStyle: this.fontStyle,
+            letterSpacing: this.letterSpacing,
+            ...this.lineOptions(),
         };
     }
     /** The orphan/widow minimums for this paragraph; unset means the CSS default of 2 lines each. */
@@ -254,15 +252,16 @@ export class TextElement extends SizedPDFElement {
     }
     // 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, indent = this.textIndent) {
+    cloneWithContent(content, indent = this.textIndent, piece = {}) {
         return new TextElement({
-            content,
+            // Cut from `display()`, already recased - a span's own transform too.
+            content: content.map((seg) => (seg.textTransform ?? "none") === "none" ? seg : { ...seg, textTransform: "none" }),
             fontSize: this.fontSize,
             fontFamily: this.fontFamily,
             fontStyle: this.fontStyle,
             color: this.color,
             textAlignment: this.textAlignment,
-            maxLines: this.maxLines,
+            maxLines: piece.maxLines ?? this.maxLines,
             orphans: this.orphans,
             widows: this.widows,
             overflow: this.overflow,
@@ -275,46 +274,92 @@ export class TextElement extends SizedPDFElement {
             wordSpacing: this.wordSpacing,
             textIndent: indent,
             role: this.role,
-        }).adoptStructId(this); // a wrapped remainder is the SAME logical paragraph (one P across pages)
+            fontFallback: this.fontFallback,
+            // Already recased: `capitalize` again would capitalise the half of a word continued on the next
+            // page.
+            textTransform: "none",
+            breakWord: this.breakWord,
+            hyphenate: this.hyphenate,
+            ligatures: this.ligatures,
+            shownLines: piece.shownLines,
+        }).asPieceOf(this); // a wrapped remainder is the SAME logical paragraph (one P across pages)
     }
     calculateLayout(constraints, offset, ctx) {
-        this.resolveStyle(ctx);
+        const { size, lines } = this.sizeWith(constraints, ctx);
         this.x = offset.x;
         this.y = offset.y;
-        // 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.resolved, this.fontSize, this.fontFamily, this.fontStyle, ctx.metrics, wrapWidth, this.maxLines, this.overflow, this.lineHeight, this.letterSpacing, this.lineOptions());
+        const lost = [...new Set([...this.lostBefore, ...this.lostGlyphs])];
+        if (lost.length > 0)
+            ctx.metrics.reportMissingGlyph?.(lost, this, pageOf(ctx));
+        this.width = size.width;
+        this.height = size.height;
+        // A line with a piece that could not break is drawn past the edge - say so.
+        const overrun = Math.max(0, ...lines.map((line) => line.overrun));
+        if (constraints.hasBoundedWidth && overrun > 0.01) {
+            diagnose(ctx.diagnostics, {
+                code: "overflow-wide",
+                severity: "warning",
+                message: `A line of this Text runs ${Math.round(overrun)}pt past its ${Math.round(size.width)}pt; ` +
+                    "a word in it cannot break. Let it break (`breakWord`, `hyphenate`), make room, or clip " +
+                    'with a Box\'s `overflow: "hidden"`.',
+                about: this,
+                page: pageOf(ctx),
+                fallback: "silent",
+            });
+        }
         // 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.
-        return { width: wrapWidth, height: this.height };
+        return size;
+    }
+    /**
+     * The size `calculateLayout` would take, without placing anything. Resolving the inherited style
+     * and filling the memos below are its only writes, and both are a pure function of the context:
+     * the same inputs leave the same state, which a later layout reads back unchanged.
+     */
+    /** A text's size reads only the width it may take: it wraps to it, and a height bound never changes
+     *  the lines (a box that is too short cuts them, it does not reflow them). */
+    sizeInputs(constraints) {
+        return BoxConstraints.loose(constraints.maxWidth, Infinity);
+    }
+    computeSize(constraints, ctx) {
+        return this.sizeWith(constraints, ctx).size;
+    }
+    /**
+     * The one sizing path, for measuring and layout alike: a bounded width wraps to it (in a Column), an
+     * unbounded one takes the natural single-line width (in a Row). The lines are what layout checks.
+     * The style is resolved here, as drawing reads it.
+     */
+    /** The text broken at `width`: once per context and width, for measuring, layout and splitting. */
+    linesAt(width, ctx) {
+        return this.broken.get(ctx, width, () => breakSegmentsIntoLines(this.display(ctx.metrics), this.segmentDefaults(), width, ctx.metrics, this.maxLines, this.overflow));
+    }
+    sizeWith(constraints, ctx) {
+        this.resolveStyle(ctx);
+        const width = constraints.hasBoundedWidth
+            ? constraints.maxWidth
+            : this.naturalWidth(ctx.metrics);
+        const defaults = this.segmentDefaults();
+        const lines = this.linesAt(width, ctx);
+        return {
+            size: { width, height: linesHeight(lines, defaults, ctx.metrics, this.lineHeight) },
+            lines,
+        };
     }
     /** The unwrapped single-line width of the content (used when width is unbounded, e.g. inside a Row).
-     *  Must match the LINE-BREAKER's one-line measure EXACTLY - not just algebraically but BIT-for-bit,
-     *  so a text laid out at this width never re-wraps inside its own natural-width box. The breaker
-     *  accumulates `currentWidth += wordWidth + spaceWidth`, grouping the word and its trailing space
-     *  into one term; we must group the same way. Adding word and space as two separate steps is
-     *  algebraically equal but, because floating-point addition is not associative, drifts by a sub-ULP
-     *  - 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. */
+     *  Must match the breaker's one-line sum BIT for bit - it adds `width + (space + word)`, and the same
+     *  numbers grouped differently drift by a sub-ULP, enough to wrap a text inside its own natural-width
+     *  box. `singleLineWidth` is that sum. */
     naturalWidth(metrics) {
-        // 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);
+        const defaults = this.segmentDefaults();
         // 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 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);
+        return this.display(metrics).reduce((sum, seg) => {
+            // The breaker's own sum, to the last bit - see `singleLineWidth`.
+            const run = runStyleOf(seg, defaults);
+            return (sum + singleLineWidth(seg.content, run.font, metrics, run.letterSpacing, run.wordSpacing));
+        }, indent);
     }
     /**
      * The widest piece of this text that cannot be broken - CSS's `min-content` width. A shrinking flex
@@ -331,27 +376,22 @@ export class TextElement extends SizedPDFElement {
             return 0;
         this.resolveStyle(ctx);
         const metrics = ctx.metrics;
-        const widest = (text, family, size, style, letterSpacing) => {
-            // `ligatures` belongs to the FONT: it decides which glyphs are drawn and therefore how wide the
-            // piece is. Leaving it out here would measure a floor the drawing never matches.
-            const font = {
-                fontFamily: family,
-                fontSize: size,
-                fontStyle: style,
-                ligatures: this.ligatures,
-            };
-            // Split on the same boundaries the breaker uses - a hard break ends a line too.
-            const pieces = this.breakWord || this.hyphenate ? [...text] : text.split(/[ \n]/);
-            return pieces.reduce((max, piece) => Math.max(max, runAdvance(metrics, piece, font, letterSpacing)), 0);
+        // The run style is the FONT a piece is measured in: `ligatures` decides which glyphs are drawn and
+        // therefore how wide it is. Leaving it out would measure a floor the drawing never matches.
+        const widest = (text, run) => {
+            // Split on the same boundaries the breaker uses - a hard break ends a line too, and so may a
+            // hyphen inside a word. A run that may split its words may split them anywhere.
+            const pieces = run.splitting.breakWord || run.splitting.hyphenate
+                ? [...text]
+                : text.split(/[ \n]/).flatMap(hyphenPieces);
+            return pieces.reduce((max, piece) => Math.max(max, runAdvance(metrics, piece, run.font, run.letterSpacing)), 0);
         };
+        const defaults = this.segmentDefaults();
         const content = this.display(metrics);
-        if (typeof content === "string") {
-            return widest(content, this.fontFamily, this.fontSize, this.fontStyle, this.letterSpacing);
-        }
         // Segments join without a space, so a word may straddle two of them; taking the widest piece per
         // segment can therefore UNDER-estimate. That errs towards squeezing a little too far, which lands
         // back on the old overflow behaviour rather than on something new.
-        return content.reduce((max, seg) => Math.max(max, widest(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontSize ?? this.fontSize, seg.fontStyle ?? this.fontStyle, seg.letterSpacing ?? this.letterSpacing)), 0);
+        return content.reduce((max, seg) => Math.max(max, widest(seg.content, runStyleOf(seg, defaults))), 0);
     }
     getProps() {
         return {
@@ -363,7 +403,11 @@ export class TextElement extends SizedPDFElement {
             fontFamily: this.fontFamily,
             fontStyle: this.fontStyle,
             color: this.color,
-            content: this.resolved ?? this.content,
+            content: this.content,
+            /** The content as it is measured and drawn: spans, recased, split by font, drawable glyphs only. */
+            spans: this.resolved ?? this.display(),
+            /** How the text is broken - the settings it is measured with, so drawing breaks it the same. */
+            breaking: this.segmentDefaults(),
             textAlignment: this.textAlignment,
             maxLines: this.maxLines,
             orphans: this.orphans,
@@ -381,6 +425,7 @@ export class TextElement extends SizedPDFElement {
             ligatures: this.ligatures,
             hyphenate: this.hyphenate,
             role: this.role,
+            shownLines: this.shownLines,
         };
     }
 }

package/dist/forms/acroform.d.ts

@@ -19,6 +19,14 @@ export declare class AcroFormCollector {
     /** 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;
+    /**
+     * The font a field's baked appearance draws its text in: the font the field inherits when it is
+     * EMBEDDED, else the standard Helvetica. PDF/A and PDF/UA require every font that draws to be
+     * embedded, and a document that embeds its fonts means that. The /DA keeps naming Helvetica - it is
+     * what a viewer redraws with once someone types, and a subset font could not draw the new characters.
+     * Measuring and drawing both take the font from here.
+     */
+    private faceFont;
     /** Measure one line for the appearance generator. */
     private line;
     /** Bake a text field's value into an appearance stream; returns the XObject number. */
@@ -47,7 +55,7 @@ export declare class AcroFormCollector {
     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;
+    addField(node: FormFieldNode, om: PDFObjectManager, structParent?: number): 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. */