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

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

@@ -2,6 +2,7 @@ import type { FontMetrics } from "../utils/font-metrics.js";
 import type { PDFPageConfig } from "./page-element.js";
 import type { ResolvedTextStyle } from "../text/text-style.js";
 import type { OverflowPolicy } from "../layout/fragmentation.js";
+import type { Diagnostics } from "../common/diagnostics.js";
 import type { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
 import type { CrossAlign } from "../layout/alignment.js";
 /**
@@ -11,18 +12,14 @@ import type { CrossAlign } from "../layout/alignment.js";
  * height. The PDF byte writer is deliberately absent - layout must not touch it.
  */
 /**
- * A positioning frame - the CSS "containing block" that `Positioned` children resolve their
- * offsets against. A `relative` Box (later the page) creates one and threads it to its subtree;
- * `Positioned` descendants register a placement closure in `place`, which the frame drains once it
- * has finished sizing itself (so `right`/`bottom` can resolve against the final box).
+ * A positioning frame - the CSS "containing block" that `Positioned` children resolve their offsets
+ * against: the page's content box, or a `relative` Box. Threaded to the subtree so a `Positioned`
+ * can tell it has one. The frame's owner finds its `Positioned` descendants by walking the tree
+ * after sizing itself, and lays them out against its own box - layout itself registers nothing.
  */
 export interface PositioningFrame {
     origin: Offset;
     size: Size;
-    place: Array<(frame: {
-        origin: Offset;
-        size: Size;
-    }, ctx: LayoutContext) => void>;
 }
 /**
  * What a `PageBuilder` learns about the page it landed on. `pageNumber` is 1-based and counts PHYSICAL
@@ -62,24 +59,104 @@ export interface LayoutContext {
     /** What to do when an element overflows a page region and cannot break (set from the render option;
      *  absent = clip silently). Evaluated in `packChildren` where the forced placement happens. */
     onOverflow?: OverflowPolicy;
-    /** The FULL body height of the current page (between header and footer), set by the page driver. A
-     *  `keepTogether` group reads it to decide the degrade rule: veto splitting only when the group would
-     *  fit on a fresh page; a group taller than a whole page drops the veto and splits. */
+    /** The render's diagnostics channel. Never part of a size, so never part of the layout-cache key;
+     *  absent when an element is laid out on its own, which then warns as before. */
+    diagnostics?: Diagnostics;
+    /** The physical page (1-based) pagination is filling - only so a diagnostic can name it; the render
+     *  pass knows it as `pageInfo`. Never part of a size. */
+    paginatingPage?: number;
+    /** The height a FRESH page gives this region: the page body (between header and footer, set by the
+     *  page driver) minus what encloses the region on every page - a border, padding, a repeated table
+     *  header (`insetContext`). A `keepTogether` group reads it to decide the degrade rule: veto splitting
+     *  only when the group would fit on a fresh page; a group taller than that drops the veto and splits. */
     pageBodyHeight?: number;
+    /** Something already sits above this element in the current page region. Then "does not fit"
+     *  means "move to the next page", never an overflow - only content at the top of a fresh page is
+     *  forced on and reported. Set by `packChildren`; absent = top of the page. */
+    belowContent?: boolean;
+    /** Packing into a Region of a `Flow`, where a `ColumnBreak` moves on to the next Region. */
+    inFlowRegion?: boolean;
+    /** Laying out a page of a `Flow`'s template: the page a `Region` laid out here belongs to. */
+    flowPage?: object;
+    /** What a `Box`'s percentage padding resolves against (CSS: the containing block). A Row sets it for
+     *  its children - it offers them no width, so the Box could not know it; otherwise the Box sets it
+     *  from what it was offered. Consumed by the Box's own padding, so it never travels further down. */
+    boxPaddingBase?: number;
 }
+/** `ctx` with `boxPaddingBase` set to `base` - the same object when nothing changes. */
+export declare function withPaddingBase(ctx: LayoutContext, base: number | undefined): LayoutContext;
 export declare abstract class PDFElement {
     private _structId;
     get structId(): number;
     /** Make this element share `from`'s tagging identity - used by fragmentation clones. Returns this. */
     adoptStructId(from: PDFElement): this;
+    /**
+     * Marks this element as a piece of `original`, split across pages: it is the same element to a
+     * reader of the tagged PDF (one structure element) and to the Row or Column it sits in (its flex
+     * properties). Every fragmentation clone ends in this call, so a property added to the base is
+     * carried in ONE place. Returns this.
+     */
+    asPieceOf(original: PDFElement): this;
+    /** Takes the flex properties `original` set (CSS `align-self`, `order`, `flex-shrink`). Returns this. */
+    takeFlexItemFrom(original: PDFElement): this;
     abstract getProps(): unknown;
     /**
      * Lays the element out: `constraints` bound its size (flows DOWN), `offset` is the
-     * absolute top-left position the parent assigns it, and the returned `Size` is the
+     * top-left position the parent assigns it, relative to the parent's own top-left (absolute
+     * coordinates exist only in the render pass), and the returned `Size` is the
      * space it actually took (flows UP). Layout works in a top-left origin; the Y-flip
      * happens once at the IR -> backend seam.
      */
     abstract calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /**
+     * The size `calculateLayout` would return under these constraints - with NO side effects: no
+     * position, no stored size, nothing registered with a frame. A parent asks this to decide, and lays
+     * a child out once afterwards; asking with a full layout doubled the work at every nesting level.
+     * Do not override it - implement `computeSize` (as Flutter's `getDryLayout` / `computeDryLayout`).
+     * The same question twice is answered from the layout cache (`layout/layout-cache.ts`).
+     */
+    measure(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /**
+     * The part of the constraints this element's size actually reads - what the layout cache keys on.
+     * All of it by default. An element whose size ignores a bound returns it opened up, so two questions
+     * that differ only there share one answer. It must be TRUE for `computeSize`: reading a bound that
+     * is dropped here makes the cache hand back a wrong size.
+     */
+    protected sizeInputs(constraints: BoxConstraints): BoxConstraints;
+    private sizeCache?;
+    /**
+     * Whether this element's size can depend on the page it lands on (`pageConfig`, `pageInfo`): a
+     * `PageBuilder`, a `Page`, and everything holding one. Only those key a cached size on the page, so
+     * every other size is reused across pages and across the pagination and render passes. Remembered:
+     * the tree does not change, and an answer that was `false` can never become `true`.
+     */
+    dependsOnPage(): boolean;
+    private pageDependent?;
+    /**
+     * How this element sizes itself for `measure`. It must come from the SAME sizing computation as
+     * `calculateLayout`, or a measured size and a laid-out one can differ.
+     */
+    protected abstract computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /**
+     * A copy of this element and of every element it holds, as it was built - to place one element
+     * twice, which a single instance cannot (it has one position). Everything else stays shared: an
+     * image's pixels, a callback. The copy tags as an element of its own.
+     */
+    clone(): this;
+    /** The elements this one lays out, for walks that must see the whole tree. Leaves have none. */
+    layoutChildren(): readonly PDFElement[];
+    /**
+     * The element this one is transparent for, if any: a `ProxyElement` returns its child. A surrounding
+     * Row or Column looks through it for the flex item (`layout/flex-item.ts`).
+     */
+    proxied(): PDFElement | undefined;
+    /** The context the element `proxied()` names is laid out in: this one's, unless it hands something
+     *  down (a `DefaultTextStyle`). */
+    proxiedContext(ctx: LayoutContext): LayoutContext;
+    /** A `Box` with percentage padding: a surrounding Row tells it its own width (`boxPaddingBase`). */
+    hasPercentPadding(): boolean;
+    /** Lays out its own `Positioned` descendants (a page, a `relative` Box); a walk for them stops here. */
+    isPositioningFrame(): boolean;
     /**
      * The relative-size fraction (0..1) this element asked for on the given axis, if any (`horizontal` =
      * width). A flex parent reads it to resolve a percentage child against its OWN main size - e.g. a
@@ -87,6 +164,9 @@ export declare abstract class PDFElement {
      * fraction would have nothing to resolve against. Default: the element is not relatively sized.
      */
     relativeSizeFactor(_horizontal: boolean): number | undefined;
+    /** The most this element may be on an axis in points (its `maxWidth`/`maxHeight`): a flex line freezes
+     *  a flex child there. A percentage max resolves against what the child is given, so it is not one. */
+    maxExtent(_horizontal: boolean): number;
     /**
      * Whether this element needs a BOUNDED extent on the given axis to lay itself out (`true` for a
      * horizontal axis = width). A flex parent measures its fixed children with an unbounded main axis, so
@@ -106,15 +186,23 @@ export declare abstract class PDFElement {
      * override it; containers recurse, since a Row is only as unsqueezable as its children.
      */
     minIntrinsicMain(_horizontal: boolean, _ctx: LayoutContext): number;
+    /**
+     * Whether this element takes its height from the REGION it is fragmented into (a `Flow`), anywhere
+     * in a subtree that has no height of its own. Such an element has no natural height to measure, so
+     * the packer fragments it into the space left instead of placing it whole. Default: no.
+     */
+    needsRegion(): boolean;
     /**
      * Whether this element IS a forced page break (a `PageBreak`). The pagination packer cuts the flow
      * at such a marker: everything before it stays, everything after starts a new page. Default: no.
      */
     isPageBreak(): boolean;
+    /** Whether this element IS a `ColumnBreak`: the packer of a Flow's Region cuts there. Default: no. */
+    isColumnBreak(): boolean;
     /**
      * Whether this element is, or CONTAINS anywhere in its subtree, a forced page break. A container
      * that merely fits by height must still be fragmented when this is true, so a break nested inside
-     * it is honoured rather than swallowed. Containers override this to recurse into their children.
+     * it is honored rather than swallowed. Containers override this to recurse into their children.
      * Default: no.
      */
     hasForcedBreak(): boolean;
@@ -141,9 +229,9 @@ export declare abstract class PDFElement {
     /**
      * Where this child sits among its siblings (CSS `order`), lowest first, source order deciding ties.
      * It moves the child in the LAYOUT only - the element tree, and therefore the reading order a tagged
-     * PDF exposes, is untouched. Default 0.
+     * PDF exposes, is untouched. Unset means 0; a stack reads it through `layout/flex-item.ts`.
      */
-    order: number;
+    order?: number;
     /**
      * How willingly this child gives up main-axis space when the line overflows (CSS `flex-shrink`),
      * weighted by its own size as CSS does. Default 1, as in CSS: an overflowing line squeezes its
@@ -154,8 +242,9 @@ export declare abstract class PDFElement {
      * caution outlived its use: four of the gallery cases turned out to be overflowing their page
      * margin without anyone noticing, because nothing ever pulled them back. Shrinking is bounded from
      * below by `minIntrinsicMain`, so a child is never squeezed past what it can actually hold.
+     * Unset means 1; a stack reads it through `layout/flex-item.ts`.
      */
-    flexShrink: number;
+    flexShrink?: number;
     /** Sets `flexShrink` and returns the element. */
     withFlexShrink(shrink: number | undefined): this;
     /** Sets `order` and returns the element, so a factory can thread it through in one expression. */

package/dist/elements/pdf-element.js

@@ -1,3 +1,8 @@
+import { SizeCache } from "../layout/layout-cache.js";
+/** `ctx` with `boxPaddingBase` set to `base` - the same object when nothing changes. */
+export function withPaddingBase(ctx, base) {
+    return ctx.boxPaddingBase === base ? ctx : { ...ctx, boxPaddingBase: base };
+}
 let _nextStructId = 0;
 export class PDFElement {
     constructor() {
@@ -5,24 +10,6 @@ export class PDFElement {
         // fragmentation copies (adoptStructId), so a paragraph or table split across pages stays ONE structure
         // element. Only the elements that actually tag (Text, Image, StructGroup) read it.
         this._structId = _nextStructId++;
-        /**
-         * Where this child sits among its siblings (CSS `order`), lowest first, source order deciding ties.
-         * It moves the child in the LAYOUT only - the element tree, and therefore the reading order a tagged
-         * PDF exposes, is untouched. Default 0.
-         */
-        this.order = 0;
-        /**
-         * How willingly this child gives up main-axis space when the line overflows (CSS `flex-shrink`),
-         * weighted by its own size as CSS does. Default 1, as in CSS: an overflowing line squeezes its
-         * children back inside instead of letting them run past the edge of the box. `0` opts out and keeps
-         * a child at its natural size.
-         *
-         * This was 0 until the alpha, so that adding flexShrink could not move an existing layout. That
-         * caution outlived its use: four of the gallery cases turned out to be overflowing their page
-         * margin without anyone noticing, because nothing ever pulled them back. Shrinking is bounded from
-         * below by `minIntrinsicMain`, so a child is never squeezed past what it can actually hold.
-         */
-        this.flexShrink = 1;
     }
     get structId() {
         return this._structId;
@@ -32,6 +19,101 @@ export class PDFElement {
         this._structId = from._structId;
         return this;
     }
+    /**
+     * Marks this element as a piece of `original`, split across pages: it is the same element to a
+     * reader of the tagged PDF (one structure element) and to the Row or Column it sits in (its flex
+     * properties). Every fragmentation clone ends in this call, so a property added to the base is
+     * carried in ONE place. Returns this.
+     */
+    asPieceOf(original) {
+        return this.adoptStructId(original).takeFlexItemFrom(original);
+    }
+    /** Takes the flex properties `original` set (CSS `align-self`, `order`, `flex-shrink`). Returns this. */
+    takeFlexItemFrom(original) {
+        this.alignSelf = original.alignSelf ?? this.alignSelf;
+        this.order = original.order ?? this.order;
+        this.flexShrink = original.flexShrink ?? this.flexShrink;
+        return this;
+    }
+    /**
+     * The size `calculateLayout` would return under these constraints - with NO side effects: no
+     * position, no stored size, nothing registered with a frame. A parent asks this to decide, and lays
+     * a child out once afterwards; asking with a full layout doubled the work at every nesting level.
+     * Do not override it - implement `computeSize` (as Flutter's `getDryLayout` / `computeDryLayout`).
+     * The same question twice is answered from the layout cache (`layout/layout-cache.ts`).
+     */
+    measure(constraints, ctx) {
+        const cache = (this.sizeCache ?? (this.sizeCache = new SizeCache()));
+        const asked = this.sizeInputs(constraints);
+        const onPage = this.dependsOnPage();
+        const known = cache.get(asked, ctx, onPage);
+        if (known)
+            return known;
+        const size = this.computeSize(constraints, ctx);
+        cache.set(asked, ctx, onPage, size);
+        return size;
+    }
+    /**
+     * The part of the constraints this element's size actually reads - what the layout cache keys on.
+     * All of it by default. An element whose size ignores a bound returns it opened up, so two questions
+     * that differ only there share one answer. It must be TRUE for `computeSize`: reading a bound that
+     * is dropped here makes the cache hand back a wrong size.
+     */
+    sizeInputs(constraints) {
+        return constraints;
+    }
+    /**
+     * Whether this element's size can depend on the page it lands on (`pageConfig`, `pageInfo`): a
+     * `PageBuilder`, a `Page`, and everything holding one. Only those key a cached size on the page, so
+     * every other size is reused across pages and across the pagination and render passes. Remembered:
+     * the tree does not change, and an answer that was `false` can never become `true`.
+     */
+    dependsOnPage() {
+        return (this.pageDependent ?? (this.pageDependent = this.layoutChildren().some((child) => child.dependsOnPage())));
+    }
+    /**
+     * A copy of this element and of every element it holds, as it was built - to place one element
+     * twice, which a single instance cannot (it has one position). Everything else stays shared: an
+     * image's pixels, a callback. The copy tags as an element of its own.
+     */
+    clone() {
+        const copyOf = (value) => value instanceof PDFElement
+            ? value.clone()
+            : Array.isArray(value)
+                ? value.map(copyOf)
+                : value;
+        const copy = Object.create(Object.getPrototypeOf(this));
+        for (const [key, value] of Object.entries(this)) {
+            copy[key] = copyOf(value);
+        }
+        copy.sizeCache = undefined;
+        copy._structId = _nextStructId++;
+        return copy;
+    }
+    /** The elements this one lays out, for walks that must see the whole tree. Leaves have none. */
+    layoutChildren() {
+        return [];
+    }
+    /**
+     * The element this one is transparent for, if any: a `ProxyElement` returns its child. A surrounding
+     * Row or Column looks through it for the flex item (`layout/flex-item.ts`).
+     */
+    proxied() {
+        return undefined;
+    }
+    /** The context the element `proxied()` names is laid out in: this one's, unless it hands something
+     *  down (a `DefaultTextStyle`). */
+    proxiedContext(ctx) {
+        return ctx;
+    }
+    /** A `Box` with percentage padding: a surrounding Row tells it its own width (`boxPaddingBase`). */
+    hasPercentPadding() {
+        return false;
+    }
+    /** Lays out its own `Positioned` descendants (a page, a `relative` Box); a walk for them stops here. */
+    isPositioningFrame() {
+        return false;
+    }
     /**
      * The relative-size fraction (0..1) this element asked for on the given axis, if any (`horizontal` =
      * width). A flex parent reads it to resolve a percentage child against its OWN main size - e.g. a
@@ -41,6 +123,11 @@ export class PDFElement {
     relativeSizeFactor(_horizontal) {
         return undefined;
     }
+    /** The most this element may be on an axis in points (its `maxWidth`/`maxHeight`): a flex line freezes
+     *  a flex child there. A percentage max resolves against what the child is given, so it is not one. */
+    maxExtent(_horizontal) {
+        return Infinity;
+    }
     /**
      * Whether this element needs a BOUNDED extent on the given axis to lay itself out (`true` for a
      * horizontal axis = width). A flex parent measures its fixed children with an unbounded main axis, so
@@ -64,6 +151,14 @@ export class PDFElement {
     minIntrinsicMain(_horizontal, _ctx) {
         return 0;
     }
+    /**
+     * Whether this element takes its height from the REGION it is fragmented into (a `Flow`), anywhere
+     * in a subtree that has no height of its own. Such an element has no natural height to measure, so
+     * the packer fragments it into the space left instead of placing it whole. Default: no.
+     */
+    needsRegion() {
+        return false;
+    }
     /**
      * Whether this element IS a forced page break (a `PageBreak`). The pagination packer cuts the flow
      * at such a marker: everything before it stays, everything after starts a new page. Default: no.
@@ -71,10 +166,14 @@ export class PDFElement {
     isPageBreak() {
         return false;
     }
+    /** Whether this element IS a `ColumnBreak`: the packer of a Flow's Region cuts there. Default: no. */
+    isColumnBreak() {
+        return false;
+    }
     /**
      * Whether this element is, or CONTAINS anywhere in its subtree, a forced page break. A container
      * that merely fits by height must still be fragmented when this is true, so a break nested inside
-     * it is honoured rather than swallowed. Containers override this to recurse into their children.
+     * it is honored rather than swallowed. Containers override this to recurse into their children.
      * Default: no.
      */
     hasForcedBreak() {

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

@@ -1,5 +1,5 @@
 import type { Radii } from "../ir/display-list.js";
-import type { GradientInput } from "../api/gradient.js";
+import type { GradientInput } from "../common/gradient.js";
 import { Color } from "../common/color.js";
 import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
 import { Fragmentable, FragmentResult } from "../layout/fragmentation.js";
@@ -14,7 +14,7 @@ export interface SideBorders {
 }
 interface RectangleElementParams extends SizedElement, WithChildren {
     color?: Color;
-    /** Solid colour, or a box-relative gradient the renderer resolves against this box. */
+    /** Solid color, or a box-relative gradient the renderer resolves against this box. */
     backgroundColor?: Color | GradientInput;
     borderWidth?: number;
     /** Corner radius in points - one number for all four corners, or per corner. 0 = sharp (default). */
@@ -74,13 +74,32 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
     hasForcedBreak(): boolean;
     private cloneWithChildren;
     relativeSizeFactor(horizontal: boolean): number | undefined;
+    maxExtent(horizontal: boolean): number;
     /** A box has no flex children of its own, but it must not swallow the need of the stack inside it: a
      *  `Spacer` in a box can only resolve if the box itself was given a bounded extent to pass down. With an
      *  explicit size on an axis the box already knows its extent there and asks for nothing. */
     needsBoundedMain(horizontal: boolean): boolean;
+    /** As a Column: a height of its own is the region; without one, a region-sized child needs the page's. */
+    needsRegion(): boolean;
+    /** A Box's own padding resolves a percentage against its containing block, not against the inner
+     *  width it hands its children - so it is told: the base a surrounding Row set, else what the Box was
+     *  offered. Neither (an unbounded offer outside a Row) leaves the Box's own width. */
+    private paddingContext;
+    hasPercentPadding(): boolean;
     /** A Box stacks its children vertically inside its border, which is on both sides of the axis. */
     minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /**
+     * The one sizing path. With an `offset` it lays the children out and keeps its geometry; with
+     * `null` it only measures - no field written, no child placed, no frame drained.
+     */
+    private sizeWith;
+    isPositioningFrame(): boolean;
+    /** Sorts the `zIndex` of the `Positioned` below it: a frame does, and so does a clip - what it crops
+     *  stays cropped, whatever its `zIndex`. */
+    isStackingContext(): boolean;
+    layoutChildren(): readonly PDFElement[];
     getProps(): {
         x: number;
         y: number;
@@ -93,6 +112,7 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
         radius: number | Radii;
         sideBorders: SideBorders | undefined;
         overflow: "hidden" | "visible";
+        relative: boolean;
     };
 }
 export {};