@jasy/pdf 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/elements/row-element.js

@@ -1,7 +1,9 @@
+import { flexibleOf } from "../layout/flex-item.js";
 import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
-import { FlexLayoutHelper, HORIZONTAL_AXIS } from "../utils/flex-layout.js";
+import { FlexLayoutHelper, HORIZONTAL_AXIS, } from "../utils/flex-layout.js";
 import { stackMinIntrinsic, withDeclaredExtent } from "../layout/min-intrinsic.js";
-import { FlexiblePDFElement, SizedPDFElement, } from "./pdf-element.js";
+import { diagnose, pageOf } from "../common/diagnostics.js";
+import { SizedPDFElement } from "./pdf-element.js";
 /**
  * Horizontal stack: the mirror of `ContainerElement` (Column). Children are laid out
  * left-to-right via the shared `FlexLayoutHelper` on the horizontal axis; fixed children
@@ -45,7 +47,7 @@ export class RowElement extends SizedPDFElement {
             : [this.requested.height, this.requested.heightFactor];
         if (requested.some((v) => v !== undefined))
             return false;
-        const ownFlexChild = horizontal && this.children.some((c) => c instanceof FlexiblePDFElement);
+        const ownFlexChild = horizontal && this.children.some((c) => flexibleOf(c) !== undefined);
         return ownFlexChild || this.children.some((c) => c.needsBoundedMain(horizontal));
     }
     /** A Row lays out side by side, so widths add up (gaps included) and heights overlap. */
@@ -56,6 +58,53 @@ export class RowElement extends SizedPDFElement {
     calculateLayout(constraints, offset, ctx) {
         this.x = offset.x;
         this.y = offset.y;
+        this.reportIgnoredBreak(ctx);
+        const size = this.sizeWith(constraints, ctx, "layout");
+        this.width = size.width;
+        this.height = size.height;
+        return size;
+    }
+    computeSize(constraints, ctx) {
+        return this.sizeWith(constraints, ctx, "measure");
+    }
+    /**
+     * A row is one line: nothing inside it starts a new page. A `breakBefore` / `breakAfter` in a cell
+     * (a table row is a Row too) is therefore ignored - say so. A `PageBreak` reports itself.
+     */
+    reportIgnoredBreak(ctx) {
+        if (this.declaredBreak === undefined) {
+            const find = (el, depth) => {
+                if (el.breaksBefore() || el.breaksAfter())
+                    return el;
+                if (depth > 64)
+                    return null;
+                for (const child of el.layoutChildren()) {
+                    const hit = find(child, depth + 1);
+                    if (hit)
+                        return hit;
+                }
+                return null;
+            };
+            this.declaredBreak = null;
+            for (const child of this.layoutChildren()) {
+                this.declaredBreak = find(child, 0);
+                if (this.declaredBreak)
+                    break;
+            }
+        }
+        if (!this.declaredBreak)
+            return;
+        diagnose(ctx.diagnostics, {
+            code: "break-ignored",
+            severity: "warning",
+            message: "breakBefore / breakAfter inside a Row (or a table row) has no effect: a row is one line and " +
+                "never starts a new page. Put the break on the Row itself, or on a child of a Column.",
+            about: this.declaredBreak,
+            page: pageOf(ctx),
+        });
+    }
+    /** The one sizing path: `layout` places the children (relative to this box), `measure` only sizes them. */
+    sizeWith(constraints, ctx, mode) {
         // Relative sizing: a pinned extent (fixed or a fraction of the offered box, clamped) wins; else
         // width fills the offered space (flex children split the leftover) and height is the tallest child.
         const specs = extentSpecs(this.requested);
@@ -77,18 +126,19 @@ export class RowElement extends SizedPDFElement {
         const crossAvail = boundedHeight ?? Infinity;
         let result = { mainUsed: 0, crossUsed: 0 };
         if (this.children.length > 0) {
-            result = FlexLayoutHelper.layout(this.children, HORIZONTAL_AXIS, mainAvail, crossAvail, this.x, this.y, {
+            result = FlexLayoutHelper.layout(this.children, HORIZONTAL_AXIS, mainAvail, crossAvail, {
                 gap: this.gap,
                 main: this.main,
                 cross: this.cross,
                 reverse: this.reverse,
                 wrap: this.wrap,
                 alignContent: this.alignContent,
-            }, ctx);
+            }, ctx, mode);
         }
-        this.width = boundedWidth ?? result.mainUsed;
-        this.height = boundedHeight ?? result.crossUsed;
-        return { width: this.width, height: this.height };
+        return { width: boundedWidth ?? result.mainUsed, height: boundedHeight ?? result.crossUsed };
+    }
+    layoutChildren() {
+        return this.children;
     }
     getProps() {
         return {

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

@@ -1,7 +1,7 @@
 import { type SvgSize } from "../svg/index.js";
 import { BoxConstraints, Offset, Size, SizingParams } from "../layout/box-constraints.js";
 import { LayoutContext, SizedPDFElement } from "./pdf-element.js";
-/** Markup, a file path (Node only), or the file's bytes. */
+/** Markup, a URL (`http(s):`, `data:`), a file path (Node only), or the file's bytes. */
 export type SvgSource = string | Uint8Array;
 interface SvgElementParams extends SizingParams {
     source: SvgSource;
@@ -16,26 +16,50 @@ interface SvgElementParams extends SizingParams {
  *
  * 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 declare class SvgElement extends SizedPDFElement {
-    private source;
-    private intrinsic;
+    private source?;
+    private intrinsic?;
+    private readonly url?;
+    private loading?;
+    private failed;
     private alt?;
     private requested;
     private sizing;
     private widthFactor?;
     private heightFactor?;
     constructor(params: SvgElementParams);
+    /**
+     * 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.
+     */
+    private parse;
+    /**
+     * 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.
+     */
+    load(fresh?: boolean): Promise<void>;
+    /**
+     * 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.
+     */
+    resolveIntrinsicSize(): Promise<void>;
     getProps(): {
         x: number;
         y: number;
         width: number | undefined;
         height: number | undefined;
-        source: string;
-        intrinsic: SvgSize;
+        source: string | undefined;
+        intrinsic: SvgSize | undefined;
         alt: string | undefined;
     };
     calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    protected computeSize(constraints: BoxConstraints): Size;
+    /** Its size under these constraints - the one computation both `measure` and layout use. */
+    private sizeFor;
 }
 export {};

package/dist/elements/svg-element.js

@@ -2,6 +2,8 @@ import { readFileBytes } from "../platform/node-fs.js";
 import { SvgParseError, svgSize, svgToIr } from "../svg/index.js";
 import { extentSpecs, resolveSize, } 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,12 +133,22 @@ export class SvgElement extends SizedPDFElement {
         let w = resolved.width;
         let h = resolved.height;
         const bounds = resolved.constraints;
+        // 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`);
+        }
         // 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;
+        const intrinsic = this.intrinsic ?? { width: 0, height: 0 };
+        if (this.sizing.aspectRatio === undefined && intrinsic.width > 0 && intrinsic.height > 0) {
+            const ratio = intrinsic.width / intrinsic.height;
             if (w !== undefined && h === undefined)
                 h = bounds.constrainHeight(w / ratio);
             else if (h !== undefined && w === undefined)
@@ -86,8 +156,9 @@ export class SvgElement extends SizedPDFElement {
         }
         // 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 {
@@ -83,6 +83,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?;
@@ -123,13 +126,26 @@ 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
+     * split each walk the whole text, and every measure, break and draw asks again.
+     *
+     * COMPARED, not cleared in `resolveStyle`: that runs on every pass and resolves to the same values,
+     * so clearing would drop the answer exactly when it is about to be reused.
+     */
+    private displayed?;
     /** 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. */
     /**
@@ -145,7 +161,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;
@@ -153,23 +169,29 @@ 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;
+    private measuredHeight;
     /** 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
@@ -190,6 +212,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;
@@ -207,6 +233,7 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
         ligatures: boolean;
         hyphenate: Hyphenator | undefined;
         role: TextRole | undefined;
+        shownLines: number | undefined;
     };
 }
 export {};