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

package/dist/elements/svg-element.js

@@ -1,7 +1,9 @@
 import { readFileBytes } from "../platform/node-fs.js";
 import { SvgParseError, svgSize, svgToIr } from "../svg/index.js";
-import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
+import { extentSpecs, resolveSize, sizeAtOwnRatio, } from "../layout/box-constraints.js";
 import { SizedPDFElement } from "./pdf-element.js";
+import { IMAGE_FETCH_LIMITS, ImageUrlError, isImageUrl } from "./image-element.js";
+import { fetchBytes } from "../utils/fetch-bytes.js";
 /** Markup is recognised by its first non-space character - anything else is treated as a path. */
 const looksLikeMarkup = (value) => /^\s*[<]/.test(value);
 /**
@@ -24,30 +26,78 @@ function readSource(path) {
  *
  * Unlike a bitmap it needs no decoder, so its intrinsic size is known SYNCHRONOUSLY, in the
  * constructor - which also means a broken file fails on the line that asked for it rather than deep
- * inside a later render, the same bargain `addFont` makes.
+ * inside a later render, the same bargain `addFont` makes. An SVG from a URL is the exception: like
+ * an image from a URL it is fetched when the document renders (`resolveIntrinsicSize`, or the
+ * renderer for a subtree built during layout), and a dead link stops the render naming it.
  */
 export class SvgElement extends SizedPDFElement {
     constructor(params) {
         super({ x: 0, y: 0, width: params.width, height: params.height });
+        this.failed = false;
         const { source, alt, widthFactor, heightFactor, ...sizing } = params;
         this.widthFactor = widthFactor;
         this.heightFactor = heightFactor;
-        this.source =
-            typeof source === "string"
+        if (typeof source === "string" && isImageUrl(source))
+            this.url = source;
+        else
+            this.parse(typeof source === "string"
                 ? looksLikeMarkup(source)
                     ? source
                     : new TextDecoder().decode(readSource(source))
-                : new TextDecoder().decode(source);
-        // Parsed here on purpose: an unreadable file is an error where it was NAMED, not inside a render
-        // three call frames later. The whole document is walked, not just its root, so an element outside
-        // the subset surfaces here too - which is what makes the error predictable rather than a lottery
-        // between construction and render time. A logo parses in well under a millisecond.
-        this.intrinsic = svgSize(this.source);
-        svgToIr(this.source, { x: 0, y: 0, width: 1, height: 1 });
+                : new TextDecoder().decode(source));
         this.alt = alt;
         this.sizing = sizing;
         this.requested = { width: params.width, height: params.height };
     }
+    /**
+     * Parsed on purpose where the source is given: an unreadable file is an error where it was NAMED,
+     * not inside a render three call frames later. The whole document is walked, not just its root, so
+     * an element outside the subset surfaces here too. A logo parses in well under a millisecond.
+     */
+    parse(source) {
+        this.intrinsic = svgSize(source);
+        svgToIr(source, { x: 0, y: 0, width: 1, height: 1 });
+        this.source = source;
+    }
+    /**
+     * Fetches and parses an SVG from a URL - once per render, however often it is asked. A no-op
+     * otherwise. A failure sticks for that render only: `fresh` (a new render begins) asks again.
+     */
+    async load(fresh = false) {
+        const url = this.url;
+        if (url === undefined)
+            return;
+        if (fresh && this.failed)
+            this.loading = undefined;
+        this.loading ?? (this.loading = fetchBytes(url, "SVG", ImageUrlError, IMAGE_FETCH_LIMITS)
+            .then((bytes) => {
+            try {
+                this.parse(new TextDecoder().decode(bytes));
+            }
+            catch (e) {
+                throw new ImageUrlError(`the SVG at ${url} could not be read: ${String(e?.message ?? e)}`);
+            }
+        })
+            .then(() => {
+            this.failed = false;
+        }, (e) => {
+            this.failed = true;
+            throw e;
+        }));
+        await this.loading;
+    }
+    /**
+     * The pre-layout pass, as for an `ImageElement`: best-effort, so a failure leaves the size unknown
+     * and the renderer, which loads again, surfaces the real error.
+     */
+    async resolveIntrinsicSize() {
+        try {
+            await this.load(true); // a render begins here
+        }
+        catch {
+            // the renderer reports it
+        }
+    }
     getProps() {
         return {
             x: this.x,
@@ -60,8 +110,18 @@ export class SvgElement extends SizedPDFElement {
         };
     }
     calculateLayout(constraints, offset, _ctx) {
+        const size = this.sizeFor(constraints);
         this.x = offset.x;
         this.y = offset.y;
+        this.width = size.width;
+        this.height = size.height;
+        return size;
+    }
+    computeSize(constraints) {
+        return this.sizeFor(constraints);
+    }
+    /** Its size under these constraints - the one computation both `measure` and layout use. */
+    sizeFor(constraints) {
         const specs = extentSpecs({
             ...this.sizing,
             width: this.requested.width,
@@ -73,21 +133,26 @@ export class SvgElement extends SizedPDFElement {
         let w = resolved.width;
         let h = resolved.height;
         const bounds = resolved.constraints;
-        // One pinned axis derives the other from the drawing's own ratio (CSS `width: 120; height: auto`).
-        // A bitmap needs a decode pass before it can do this; an SVG knows it from its viewBox.
-        if (this.sizing.aspectRatio === undefined &&
-            this.intrinsic.width > 0 &&
-            this.intrinsic.height > 0) {
-            const ratio = this.intrinsic.width / this.intrinsic.height;
-            if (w !== undefined && h === undefined)
-                h = bounds.constrainHeight(w / ratio);
-            else if (h !== undefined && w === undefined)
-                w = bounds.constrainWidth(h * ratio);
+        // An SVG from a URL that was never fetched sits in content built DURING layout (a PageBuilder, an auto
+        // table column), which the pass before layout cannot reach. Its ratio is unknown here, so it needs
+        // its whole box - a named error instead of a drawing sized to nothing. A FAILED fetch is not this
+        // case: the renderer reports that one by its URL.
+        if (this.url !== undefined &&
+            this.loading === undefined &&
+            (w === undefined || h === undefined)) {
+            throw new ImageUrlError(`the SVG at ${this.url} sits in content built during layout (a PageBuilder or an auto table ` +
+                `column), where its size cannot be read before it is placed - give it both a width and a ` +
+                `height, or an aspectRatio`);
+        }
+        // Its own ratio fills an open axis, as for a bitmap - which needs a decode pass for it; an SVG
+        // knows it from its viewBox. Unsized, it is its own size scaled down to fit: a 24pt icon stays 24pt.
+        const intrinsic = this.intrinsic ?? { width: 0, height: 0 };
+        if (this.sizing.aspectRatio === undefined && intrinsic.width > 0 && intrinsic.height > 0) {
+            ({ width: w, height: h } = sizeAtOwnRatio(w, h, intrinsic, bounds));
         }
-        // Nothing pinned: draw at the intrinsic size, as an unsized `<img>` does - never fill the region,
-        // which would blow a 24pt icon up to the whole page.
-        this.width = w ?? bounds.constrainWidth(this.intrinsic.width);
-        this.height = h ?? bounds.constrainHeight(this.intrinsic.height);
-        return { width: this.width, height: this.height };
+        return {
+            width: w ?? bounds.constrainWidth(intrinsic.width),
+            height: h ?? bounds.constrainHeight(intrinsic.height),
+        };
     }
 }

package/dist/elements/text-element.d.ts

@@ -4,7 +4,7 @@ import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
 import type { Direction } from "../text/bidi.js";
 import { type TextTransform } from "../text/text-style.js";
 import { Fragmentable, FragmentResult } from "../layout/fragmentation.js";
-import { TextOverflow } from "../text/line-breaker.js";
+import { type SegmentDefaults, TextOverflow } from "../text/line-breaker.js";
 import { HorizontalAlignment, LayoutContext, SizedPDFElement } from "./pdf-element.js";
 import type { Hyphenator } from "../text/word-splitting.js";
 export interface TextSegment {
@@ -22,8 +22,16 @@ export interface TextSegment {
     /** Unset inherits the Text's own setting; `true`/`false` overrides it for this run only. */
     underline?: boolean;
     strikethrough?: boolean;
+    skipInk?: boolean;
     /** Extra space after every glyph, in points; unset inherits the Text's own value. */
     letterSpacing?: number;
+    textTransform?: TextTransform;
+    wordSpacing?: number;
+    ligatures?: boolean;
+    /** How a word wider than the box splits, for the characters of THIS run (Chrome: a break after a
+     *  character is allowed by that character's own `overflow-wrap`). */
+    breakWord?: boolean;
+    hyphenate?: Hyphenator;
     /**
      * CSS `vertical-align`, for a footnote marker or a formula index. Shifts THIS run's baseline;
      * it does not resize the text, and it does not change the line's height - set `fontSize` yourself
@@ -83,6 +91,9 @@ interface TextElementParams {
     hyphenate?: Hyphenator;
     /** Accessibility role for the tagged structure tree (heading level or paragraph; default `"p"`). */
     role?: TextRole;
+    /** Set by pagination, not by authors: this element is the first N lines of a paragraph that
+     *  continues on the next page. See `LineOptions.shownLines`. */
+    shownLines?: number;
 }
 export declare class TextElement extends SizedPDFElement implements Fragmentable {
     private readonly rawFontSize?;
@@ -116,6 +127,7 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
     private direction;
     private fontFallback;
     private resolved?;
+    private broken;
     private textTransform;
     private wordSpacing;
     private textIndent;
@@ -123,12 +135,17 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
     private ligatures;
     private hyphenate?;
     private content;
+    /** 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`. */
+    private lostGlyphs;
+    private lostBefore;
     private maxLines?;
     private orphans?;
     private widows?;
     private overflow;
     private readonly role?;
-    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, orphans, widows, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, fontFallback, textTransform, wordSpacing, textIndent, breakWord, hyphenate, ligatures, role, }: TextElementParams);
+    private readonly shownLines?;
+    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, orphans, widows, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, fontFallback, textTransform, wordSpacing, textIndent, breakWord, hyphenate, ligatures, role, shownLines, }: TextElementParams);
     private resolveStyle;
     /**
      * The last `display(metrics)` result, with what it depended on - recasing, coverage and the fallback
@@ -153,7 +170,7 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
      * back unchanged, so an ordinary document is byte-identical.
      */
     private covered;
-    /** The content with `text-transform` applied, and nothing else. */
+    /** The content as spans, with `text-transform` applied, and nothing else. */
     private recased;
     private lineOptions;
     private applyStyle;
@@ -161,23 +178,36 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
      * 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: number, width: number, ctx: LayoutContext): FragmentResult;
-    private fragmentString;
-    private fragmentSegments;
+    /** How the text is broken: the knobs `textHeight` and the renderer pass too. */
+    private segmentDefaults;
     /** The orphan/widow minimums for this paragraph; unset means the CSS default of 2 lines each. */
     private breakRule;
     private cloneWithContent;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): 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). */
+    protected sizeInputs(constraints: BoxConstraints): BoxConstraints;
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): 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. */
+    private linesAt;
+    private sizeWith;
     /** 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. */
     private naturalWidth;
     /**
      * The widest piece of this text that cannot be broken - CSS's `min-content` width. A shrinking flex
@@ -198,6 +228,10 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
         fontStyle: FontStyle;
         color: Color;
         content: string | TextSegment[];
+        /** The content as it is measured and drawn: spans, recased, split by font, drawable glyphs only. */
+        spans: TextSegment[];
+        /** How the text is broken - the settings it is measured with, so drawing breaks it the same. */
+        breaking: SegmentDefaults;
         textAlignment: HorizontalAlignment;
         maxLines: number | undefined;
         orphans: number | undefined;
@@ -215,6 +249,7 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
         ligatures: boolean;
         hyphenate: Hyphenator | undefined;
         role: TextRole | undefined;
+        shownLines: number | undefined;
     };
 }
 export {};