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

package/dist/elements/layout/column-break-element.d.ts

@@ -0,0 +1,17 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, PDFElement } from "../pdf-element.js";
+/**
+ * A forced break to the next Region of a `Flow` - from the last one, the next page's first. Always of
+ * the innermost Flow; several skip several. It takes no space and draws nothing: the packer of a Region
+ * consumes it, so reaching the render pass means it sat outside one, which is reported there.
+ */
+export declare class ColumnBreakElement extends PDFElement {
+    /** The page it was last laid out on - only so an ineffective break can name it. */
+    page?: number;
+    calculateLayout(_constraints: BoxConstraints, _offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(): Size;
+    isColumnBreak(): boolean;
+    /** So a container around it is packed (and the break found) instead of placed whole. */
+    hasForcedBreak(): boolean;
+    getProps(): Record<string, never>;
+}

package/dist/elements/layout/column-break-element.js

@@ -0,0 +1,26 @@
+import { PDFElement } from "../pdf-element.js";
+import { pageOf } from "../../common/diagnostics.js";
+/**
+ * A forced break to the next Region of a `Flow` - from the last one, the next page's first. Always of
+ * the innermost Flow; several skip several. It takes no space and draws nothing: the packer of a Region
+ * consumes it, so reaching the render pass means it sat outside one, which is reported there.
+ */
+export class ColumnBreakElement extends PDFElement {
+    calculateLayout(_constraints, _offset, ctx) {
+        this.page = pageOf(ctx);
+        return { width: 0, height: 0 };
+    }
+    computeSize() {
+        return { width: 0, height: 0 };
+    }
+    isColumnBreak() {
+        return true;
+    }
+    /** So a container around it is packed (and the break found) instead of placed whole. */
+    hasForcedBreak() {
+        return true;
+    }
+    getProps() {
+        return {};
+    }
+}

package/dist/elements/layout/default-text-style-element.d.ts

@@ -1,29 +1,27 @@
-import { PDFElement, LayoutContext, WithChild, SizedPDFElement } from "../pdf-element.js";
-import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
-import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
+import { PDFElement, LayoutContext, WithChild } from "../pdf-element.js";
+import { ProxyElement } from "./proxy-element.js";
 import { ResolvedTextStyle } from "../../text/text-style.js";
 interface DefaultTextStyleParams extends WithChild {
     style: Partial<ResolvedTextStyle>;
 }
 /**
  * Provides default text properties (font/size/color/lineHeight/align/weight) to its whole subtree -
- * Flutter's `DefaultTextStyle`. Transparent to layout: the child takes the same constraints, offset
- * and size; only the inherited TextStyle changes. A `Text` below still wins per property, and these
+ * Flutter's `DefaultTextStyle`. Transparent to layout (a `ProxyElement`): only the inherited
+ * TextStyle changes. A `Text` below still wins per property, and these
  * overrides layer onto whatever the element already inherited from above.
  */
-export declare class DefaultTextStyleElement extends SizedPDFElement implements Fragmentable {
-    private child;
+export declare class DefaultTextStyleElement extends ProxyElement {
     private style;
     constructor({ child, style }: DefaultTextStyleParams);
-    private childCtx;
-    fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
-    private cloneWithChild;
-    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected childContext(ctx: LayoutContext): LayoutContext;
+    private merged?;
+    private mergedOnto;
+    protected rewrap(child: PDFElement): PDFElement;
     getProps(): {
         x: number;
         y: number;
-        width: number | undefined;
-        height: number | undefined;
+        width: number;
+        height: number;
         child: PDFElement;
     };
 }

package/dist/elements/layout/default-text-style-element.js

@@ -1,46 +1,29 @@
-import { SizedPDFElement } from "../pdf-element.js";
-import { isFragmentable } from "../../layout/fragmentation.js";
+import { ProxyElement } from "./proxy-element.js";
 import { DEFAULT_TEXT_STYLE, mergeTextStyle } from "../../text/text-style.js";
 /**
  * Provides default text properties (font/size/color/lineHeight/align/weight) to its whole subtree -
- * Flutter's `DefaultTextStyle`. Transparent to layout: the child takes the same constraints, offset
- * and size; only the inherited TextStyle changes. A `Text` below still wins per property, and these
+ * Flutter's `DefaultTextStyle`. Transparent to layout (a `ProxyElement`): only the inherited
+ * TextStyle changes. A `Text` below still wins per property, and these
  * overrides layer onto whatever the element already inherited from above.
  */
-export class DefaultTextStyleElement extends SizedPDFElement {
+export class DefaultTextStyleElement extends ProxyElement {
     constructor({ child, style }) {
-        super({ x: 0, y: 0 });
-        this.child = child;
+        super(child);
         this.style = style;
     }
-    childCtx(ctx) {
-        return {
-            ...ctx,
-            textStyle: mergeTextStyle(ctx.textStyle ?? DEFAULT_TEXT_STYLE, this.style),
-        };
+    childContext(ctx) {
+        return { ...ctx, textStyle: this.mergedOnto(ctx.textStyle ?? DEFAULT_TEXT_STYLE) };
     }
-    // Transparent to fragmentation too: split the child against the merged context, re-wrapping each
-    // half so the remainder on the next page keeps the same defaults.
-    fragment(maxHeight, width, ctx) {
-        if (!isFragmentable(this.child))
-            return { fitted: null, remainder: this };
-        const split = this.child.fragment(maxHeight, width, this.childCtx(ctx));
-        return {
-            fitted: split.fitted ? this.cloneWithChild(split.fitted) : null,
-            remainder: split.remainder ? this.cloneWithChild(split.remainder) : null,
-        };
+    mergedOnto(inherited) {
+        if (this.merged?.onto !== inherited) {
+            this.merged = { onto: inherited, style: mergeTextStyle(inherited, this.style) };
+        }
+        return this.merged.style;
     }
-    cloneWithChild(child) {
+    // Each piece of a split keeps the defaults, so the remainder on the next page looks the same.
+    rewrap(child) {
         return new DefaultTextStyleElement({ child, style: this.style });
     }
-    calculateLayout(constraints, offset, ctx) {
-        this.x = offset.x;
-        this.y = offset.y;
-        const size = this.child.calculateLayout(constraints, offset, this.childCtx(ctx));
-        this.width = size.width;
-        this.height = size.height;
-        return size;
-    }
     getProps() {
         return { x: this.x, y: this.y, width: this.width, height: this.height, child: this.child };
     }

package/dist/elements/layout/deferred-element.d.ts

@@ -2,18 +2,34 @@ import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
 import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
 import { LayoutContext, PDFElement } from "../pdf-element.js";
 /**
- * Builds its subtree at layout time via `resolve(ctx)`, so the tree can depend on font
- * metrics (e.g. a Table resolving `"auto"` column widths from cell content). The engine
- * stays table-agnostic - the closure comes from the API layer.
+ * Builds its subtree at layout time via `resolve(ctx, width)`, so the tree can depend on font
+ * metrics and on the width it gets (e.g. a Table fitting its `"auto"` and `fr` columns to the cell
+ * content and its own width). The engine stays table-agnostic - the closure comes from the API layer.
  */
 export declare class DeferredElement extends PDFElement implements Fragmentable {
     private resolve;
+    private readonly sources;
     private composed?;
-    constructor(resolve: (ctx: LayoutContext) => PDFElement);
+    private built;
+    /**
+     * `sources`: the elements the subtree will be built from (a table's cells), so the async pass before
+     * layout can reach what is not built yet - an image from a URL in a cell.
+     */
+    constructor(resolve: (ctx: LayoutContext, width: number) => PDFElement, sources?: readonly PDFElement[]);
+    /** A copy builds a subtree of its own, from copies, so even element cells it holds are its own. */
+    clone(): this;
+    /** The subtree for this context and width: built once, and again only when one of them changes. */
+    private subtree;
     private build;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /** Its subtree is unknown until built, and could hold a `PageBuilder`; until then assume it does. */
+    dependsOnPage(): boolean;
+    /** Sizes the subtree for this context - the same one a layout under it will draw. */
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+    layoutChildren(): readonly PDFElement[];
     getProps(): {
         composed: PDFElement | undefined;
+        sources: readonly PDFElement[];
     };
 }

package/dist/elements/layout/deferred-element.js

@@ -1,29 +1,61 @@
 import { isFragmentable } from "../../layout/fragmentation.js";
 import { PDFElement } from "../pdf-element.js";
+import { BuiltFromContext } from "../../layout/layout-cache.js";
+const builtOnPage = (subtree) => subtree.dependsOnPage();
 /**
- * Builds its subtree at layout time via `resolve(ctx)`, so the tree can depend on font
- * metrics (e.g. a Table resolving `"auto"` column widths from cell content). The engine
- * stays table-agnostic - the closure comes from the API layer.
+ * Builds its subtree at layout time via `resolve(ctx, width)`, so the tree can depend on font
+ * metrics and on the width it gets (e.g. a Table fitting its `"auto"` and `fr` columns to the cell
+ * content and its own width). The engine stays table-agnostic - the closure comes from the API layer.
  */
 export class DeferredElement extends PDFElement {
-    constructor(resolve) {
+    /**
+     * `sources`: the elements the subtree will be built from (a table's cells), so the async pass before
+     * layout can reach what is not built yet - an image from a URL in a cell.
+     */
+    constructor(resolve, sources = []) {
         super();
         this.resolve = resolve;
+        this.sources = sources;
+        this.built = new BuiltFromContext(builtOnPage);
     }
-    build(ctx) {
-        this.composed = this.resolve(ctx);
+    /** A copy builds a subtree of its own, from copies, so even element cells it holds are its own. */
+    clone() {
+        const copy = super.clone();
+        const resolve = this.resolve;
+        copy.resolve = (ctx, width) => resolve(ctx, width).clone();
+        copy.built = new BuiltFromContext(builtOnPage);
+        copy.composed = undefined;
+        return copy;
+    }
+    /** The subtree for this context and width: built once, and again only when one of them changes. */
+    subtree(ctx, width) {
+        return this.built.get(ctx, width, () => this.resolve(ctx, width));
+    }
+    build(ctx, width) {
+        this.composed = this.subtree(ctx, width);
         return this.composed;
     }
     calculateLayout(constraints, offset, ctx) {
-        return this.build(ctx).calculateLayout(constraints, offset, ctx);
+        return this.build(ctx, constraints.maxWidth).calculateLayout(constraints, offset, ctx);
+    }
+    /** Its subtree is unknown until built, and could hold a `PageBuilder`; until then assume it does. */
+    dependsOnPage() {
+        return this.composed?.dependsOnPage() ?? true;
+    }
+    /** Sizes the subtree for this context - the same one a layout under it will draw. */
+    computeSize(constraints, ctx) {
+        return this.subtree(ctx, constraints.maxWidth).measure(constraints, ctx);
     }
     fragment(maxHeight, width, ctx) {
-        const c = this.build(ctx);
+        const c = this.build(ctx, width);
         return isFragmentable(c)
             ? c.fragment(maxHeight, width, ctx)
             : { fitted: this, remainder: null };
     }
+    layoutChildren() {
+        return this.composed ? [this.composed] : [];
+    }
     getProps() {
-        return { composed: this.composed };
+        return { composed: this.composed, sources: this.sources };
     }
 }

package/dist/elements/layout/expanded-element.d.ts

@@ -12,7 +12,12 @@ export declare class ExpandedElement extends FlexiblePDFElement implements Fragm
     constructor({ flex, basis, basisFactor, child }: ExpandedElementParams);
     /** Layout-transparent: the floor is whatever the wrapped child needs. */
     minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
+    /** And the ceiling is the child's. */
+    maxExtent(horizontal: boolean): number;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /** The one sizing path: with an `offset` the child is laid out there, with `null` only measured. */
+    private sizeWith;
     /**
      * When the column paginates, a flex region can't "fill" across pages, so it delegates to
      * its child: the child splits and each half is re-wrapped in an Expanded (which then
@@ -20,7 +25,13 @@ export declare class ExpandedElement extends FlexiblePDFElement implements Fragm
      * whole Expanded moves on.
      */
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+    needsRegion(): boolean;
+    needsBoundedMain(horizontal: boolean): boolean;
+    hasForcedBreak(): boolean;
+    breaksBefore(): boolean;
+    breaksAfter(): boolean;
     private cloneWithChild;
+    layoutChildren(): readonly PDFElement[];
     getProps(): {
         x: number;
         y: number;

package/dist/elements/layout/expanded-element.js

@@ -15,27 +15,41 @@ export class ExpandedElement extends FlexiblePDFElement {
     minIntrinsicMain(horizontal, ctx) {
         return this.child.minIntrinsicMain(horizontal, ctx);
     }
+    /** And the ceiling is the child's. */
+    maxExtent(horizontal) {
+        return this.child.maxExtent(horizontal);
+    }
     calculateLayout(constraints, offset, ctx) {
-        if (constraints.hasBoundedWidth)
-            this.width = constraints.maxWidth;
+        Validator.validateFlexElement(this);
+        const size = this.sizeWith(constraints, ctx, offset);
         // Absolute placement from the parent; assignment (not +=) so re-layout is idempotent.
         this.x = offset.x;
         this.y = offset.y;
-        Validator.validateFlexElement(this);
-        if (constraints.hasBoundedHeight) {
-            // A bounded region: fill it - the normal flex behavior.
-            this.height = constraints.maxHeight;
-            this.child.calculateLayout(BoxConstraints.loose(this.width, this.height), { x: this.x, y: this.y }, ctx);
-        }
-        else {
-            // Unbounded (measuring while paginating): there's no leftover space to fill, so
-            // collapse to the child's natural height. This lets an overflowing column flow
-            // instead of the flex silently hiding the overflow.
-            const childSize = this.child.calculateLayout(BoxConstraints.loose(this.width, Infinity), { x: this.x, y: this.y }, ctx);
-            this.height = childSize.height;
-        }
-        // Top-left coordinates; the Y-flip now happens once at the IR -> backend seam.
-        return { width: this.width, height: this.height };
+        this.width = size.width;
+        this.height = size.height;
+        return size;
+    }
+    computeSize(constraints, ctx) {
+        return this.sizeWith(constraints, ctx, null);
+    }
+    /** The one sizing path: with an `offset` the child is laid out there, with `null` only measured. */
+    sizeWith(constraints, ctx, offset) {
+        // It fills its MAIN axis only. Across it, it is an ordinary child: with no width bound it takes
+        // its content's width, from THIS call - never one left over from an earlier layout.
+        const width = constraints.hasBoundedWidth ? constraints.maxWidth : Infinity;
+        // A bounded region: fill it - the normal flex behavior. Unbounded (measuring while paginating):
+        // there's no leftover space to fill, so collapse to the child's natural height. This lets an
+        // overflowing column flow instead of the flex silently hiding the overflow.
+        // `Expanded(child)` is `flex: 1` on the child: the extent its line SET (the min) is the child's too,
+        // so its own width or height gives way to its share - as in CSS and Flutter.
+        const childConstraints = new BoxConstraints(constraints.minWidth, width, constraints.minHeight, constraints.hasBoundedHeight ? constraints.maxHeight : Infinity);
+        const childSize = offset
+            ? this.child.calculateLayout(childConstraints, { x: offset.x, y: offset.y }, ctx)
+            : this.child.measure(childConstraints, ctx);
+        return {
+            width: constraints.hasBoundedWidth ? width : childSize.width,
+            height: constraints.hasBoundedHeight ? constraints.maxHeight : childSize.height,
+        };
     }
     /**
      * When the column paginates, a flex region can't "fill" across pages, so it delegates to
@@ -51,8 +65,26 @@ export class ExpandedElement extends FlexiblePDFElement {
         return {
             fitted: split.fitted ? this.cloneWithChild(split.fitted) : null,
             remainder: split.remainder ? this.cloneWithChild(split.remainder) : null,
+            forceBreak: split.forceBreak,
         };
     }
+    needsRegion() {
+        return this.child.needsRegion();
+    }
+    // The child IS the flex item: what it needs across the line, the line must give it.
+    needsBoundedMain(horizontal) {
+        return this.child.needsBoundedMain(horizontal);
+    }
+    // A break inside the flex child is a break in the flow it sits in.
+    hasForcedBreak() {
+        return this.child.hasForcedBreak();
+    }
+    breaksBefore() {
+        return this.child.breaksBefore();
+    }
+    breaksAfter() {
+        return this.child.breaksAfter();
+    }
     cloneWithChild(child) {
         // The basis has to come along: a fragment that lost it would claim only its share of the leftover,
         // so a `flexBasis` slot would silently change width on the page it continues onto.
@@ -61,7 +93,10 @@ export class ExpandedElement extends FlexiblePDFElement {
             basis: this.basis,
             basisFactor: this.basisFactor,
             child,
-        });
+        }).asPieceOf(this);
+    }
+    layoutChildren() {
+        return [this.child];
     }
     getProps() {
         return {

package/dist/elements/layout/flow-element.d.ts

@@ -0,0 +1,109 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { type FragmentResult } from "../../layout/fragmentation.js";
+import { ContainerElement } from "../container-element.js";
+import { LayoutContext, PDFElement, SizedPDFElement } from "../pdf-element.js";
+/** What a template is built from: `index` counts THIS Flow's pages (0 = where it starts). */
+export interface FlowPage {
+    index: number;
+    pageNumber: number;
+}
+export type FlowTemplate = (page: FlowPage) => PDFElement;
+/** A template with no `Region` would place nothing on every page, forever. */
+export declare class FlowWithoutRegionError extends Error {
+    constructor();
+}
+/** A template that leaves every Region without room, where the Flow cannot move on to find more. */
+export declare class FlowRegionsEmptyError extends Error {
+    constructor(width: number, height: number);
+}
+/** Laid out with no height to fill: every line would land in the first Region. */
+export declare class FlowUnboundedError extends Error {
+    constructor();
+}
+/** A PageBuilder builds again for the page it is drawn on, so Regions inside it lose their content. */
+export declare class RegionInPageBuilderError extends Error {
+    constructor();
+}
+/**
+ * One page of a Flow: its template, with each Region holding its content. It is drawn laid out at the
+ * height it was filled at - not at its own size, which a template that does not fill (`50%`) differs from.
+ */
+export declare class FlowPieceElement extends SizedPDFElement {
+    private readonly template;
+    private readonly size;
+    private readonly bound;
+    private readonly page;
+    constructor(template: PDFElement, size: Size, bound: number, page: object);
+    calculateLayout(_constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(): Size;
+    layoutChildren(): readonly PDFElement[];
+    getProps(): {
+        child: PDFElement;
+        width: number;
+        height: number;
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Content flowing through the Regions of a template, page after page. It has no height of its own -
+ * like an `Expanded`, it takes what it is given: the rest of the page when it is fragmented, the rest
+ * of a box with a height otherwise. On its last page it shrinks to what the content used.
+ */
+export declare class FlowElement extends SizedPDFElement {
+    private readonly content;
+    private readonly template;
+    private readonly index;
+    private readonly balance;
+    private piece?;
+    constructor({ content, template, index, balance, }: {
+        content: ContainerElement;
+        template: FlowTemplate;
+        index?: number;
+        balance?: boolean;
+    });
+    needsRegion(): boolean;
+    /** Its height comes from the parent, as an `Expanded`'s does. */
+    needsBoundedMain(horizontal: boolean): boolean;
+    /** The template is built from the page it lands on. */
+    dependsOnPage(): boolean;
+    fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /** Unbounded, it has no height of its own (a parent that bounds it asks again); bounded, it fills. */
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /**
+     * The one place a page of the Flow is made: the template at `width` x `maxHeight`, the content
+     * fragmented into its Regions in turn, and - when the content ends here - the template shrunk to
+     * what it used, or balanced.
+     */
+    private fill;
+    /**
+     * The content fragmented into the laid-out Regions in turn; each holds its piece. `fresh` is how tall
+     * each Region is on a full page - what a block that does not fit here may wait for.
+     */
+    private pour;
+    /**
+     * The last page, balanced: the smallest height at which the content, poured again, still ends here,
+     * so the Regions come out about equally full. Every candidate is a real pour - breaks,
+     * `keepTogether` and orphans hold as on any page - and the last one poured is the one drawn. A
+     * candidate is silent, and one that had to clip a block it could not break is too low.
+     */
+    private balanced;
+    /**
+     * The last page: the smallest height at which every filled Region still holds what it was given.
+     * Only a layout knows how a template's Regions answer a height (`%`, stacked, `minHeight`, fixed), so
+     * each candidate is laid out and checked. The first is exact for Regions side by side (the full bound
+     * less the smallest slack); below it the bound is searched, down to the template's own height.
+     * Content that overflowed its Region at full height asks for no more than it had there.
+     */
+    private shrink;
+    layoutChildren(): readonly PDFElement[];
+    getProps(): {
+        x: number;
+        y: number;
+        width: number | undefined;
+        height: number | undefined;
+        child: ContainerElement;
+        piece: FlowPieceElement | undefined;
+    };
+}