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

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

@@ -1,13 +1,26 @@
 import { Validator } from "../../validators/element-validator.js";
-import { SizedPDFElement } from "../pdf-element.js";
+import { SizedPDFElement, withPaddingBase, } from "../pdf-element.js";
 import { BoxConstraints } from "../../layout/box-constraints.js";
-import { isFragmentable } from "../../layout/fragmentation.js";
+import { insetContext, isFragmentable, } from "../../layout/fragmentation.js";
 import { resolveEdges } from "../../layout/insets.js";
 export class PaddingElement extends SizedPDFElement {
-    constructor({ margin, child }) {
+    constructor({ margin, child, ofBox = false }) {
         super({ x: 0, y: 0 });
         this.child = child;
         this.margin = margin;
+        this.ofBox = ofBox;
+    }
+    /** Some side is a percentage. */
+    get hasPercentSide() {
+        return this.margin.some((side) => typeof side !== "number" && side.factor !== undefined);
+    }
+    /** The width a percentage side resolves against, and the context the child sees: a Box's base is
+     *  for this padding alone, so it does not travel further down. */
+    percentBase(width, ctx) {
+        return this.ofBox && ctx.boxPaddingBase !== undefined ? ctx.boxPaddingBase : width;
+    }
+    childContext(ctx) {
+        return withPaddingBase(ctx, undefined);
     }
     /**
      * Splits the padded box across pages (box-decoration-break: clone - every fragment
@@ -19,16 +32,23 @@ export class PaddingElement extends SizedPDFElement {
         if (!isFragmentable(this.child)) {
             return { fitted: null, remainder: this };
         }
-        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, width);
+        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, this.percentBase(width, ctx));
         const childWidth = width - marginLeft - marginRight;
         const childMaxHeight = maxHeight - marginTop - marginBottom;
-        const split = this.child.fragment(childMaxHeight, childWidth, ctx);
+        const split = this.child.fragment(childMaxHeight, childWidth, insetContext(this.childContext(ctx), marginTop + marginBottom));
         return {
             fitted: split.fitted ? this.cloneWithChild(split.fitted) : null,
             remainder: split.remainder ? this.cloneWithChild(split.remainder) : null,
             forceBreak: split.forceBreak,
         };
     }
+    /** A wrapper: it needs a bound exactly when its child does, and passes the bound on. */
+    needsBoundedMain(horizontal) {
+        return this.child.needsBoundedMain(horizontal);
+    }
+    needsRegion() {
+        return this.child.needsRegion();
+    }
     hasForcedBreak() {
         return this.child.hasForcedBreak();
     }
@@ -41,7 +61,7 @@ export class PaddingElement extends SizedPDFElement {
         return this.child.breaksAfter();
     }
     cloneWithChild(child) {
-        return new PaddingElement({ margin: this.margin, child });
+        return new PaddingElement({ margin: this.margin, child, ofBox: this.ofBox }).asPieceOf(this);
     }
     /**
      * The child plus our own insets. A PERCENTAGE inset counts as zero here: it resolves against a width
@@ -52,33 +72,48 @@ export class PaddingElement extends SizedPDFElement {
         return (this.child.minIntrinsicMain(horizontal, ctx) + (horizontal ? left + right : top + bottom));
     }
     calculateLayout(constraints, offset, ctx) {
-        // Padding takes the width it is offered; its height shrink-wraps the child.
-        if (constraints.hasBoundedWidth)
-            this.width = constraints.maxWidth;
+        const size = this.sizeWith(constraints, ctx, "layout");
         this.x = offset.x;
         this.y = offset.y;
-        // Percentages resolve against the width we were OFFERED, so every pass gets the same answer.
-        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, constraints.maxWidth);
-        // The child is inset by the margins: shifted down/right, narrowed by the
-        // horizontal margins, and left height-unbounded so it sizes to its own content.
-        const childOffset = {
-            x: this.x + marginLeft,
-            y: this.y + marginTop,
-        };
+        this.width = size.width;
+        this.height = size.height;
+        Validator.validateSizedElement(this);
+        return size;
+    }
+    computeSize(constraints, ctx) {
+        return this.sizeWith(constraints, ctx, "measure");
+    }
+    /** The one sizing path: `layout` places the child (relative to this box), `measure` only sizes it. */
+    sizeWith(constraints, ctx, mode) {
+        // Percentages resolve against the width we were OFFERED (a Box's: what the Box was offered), so
+        // every pass gets the same answer.
+        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, this.percentBase(constraints.maxWidth, ctx));
+        // The child is inset by the margins: shifted down/right, narrowed by the horizontal margins, and
+        // left height-unbounded so it sizes to its own content - unless it cannot lay itself out without a
+        // bound (a stack holding a Spacer): that one gets the height inside the margins, as it would without
+        // the padding.
         const childWidth = constraints.hasBoundedWidth
             ? Math.max(0, constraints.maxWidth - marginLeft - marginRight)
             : Infinity;
-        const childConstraints = BoxConstraints.loose(childWidth, Infinity);
-        const childSize = this.child.calculateLayout(childConstraints, childOffset, ctx);
-        this.height = childSize.height + marginTop + marginBottom;
-        // Unbounded width (e.g. a fixed child in a Row): shrink-wrap to the child + insets,
-        // mirroring how Container/Row shrink-wrap. Bounded width was set above (unchanged).
-        if (!constraints.hasBoundedWidth) {
-            this.width = childSize.width + marginLeft + marginRight;
-        }
-        Validator.validateSizedElement(this);
-        // Top-left coordinates; the Y-flip now happens once at the IR -> backend seam.
-        return { width: this.width ?? 0, height: this.height };
+        const childHeight = constraints.hasBoundedHeight && this.child.needsBoundedMain(false)
+            ? Math.max(0, constraints.maxHeight - marginTop - marginBottom)
+            : Infinity;
+        const childConstraints = BoxConstraints.loose(childWidth, childHeight);
+        const childCtx = this.childContext(ctx);
+        const childSize = mode === "layout"
+            ? this.child.calculateLayout(childConstraints, { x: marginLeft, y: marginTop }, childCtx)
+            : this.child.measure(childConstraints, childCtx);
+        // Padding takes the width it is offered; its height shrink-wraps the child. Unbounded width (a
+        // fixed child in a Row) shrink-wraps to the child + insets, as Container/Row do.
+        return {
+            width: constraints.hasBoundedWidth
+                ? constraints.maxWidth
+                : childSize.width + marginLeft + marginRight,
+            height: childSize.height + marginTop + marginBottom,
+        };
+    }
+    layoutChildren() {
+        return [this.child];
     }
     getProps() {
         return {

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

@@ -10,7 +10,10 @@ import { LayoutContext, PDFElement } from "../pdf-element.js";
  * too. A break wins over a `keepTogether` (a forced break cannot be avoided) - CSS behaves the same.
  */
 export declare class PageBreakElement extends PDFElement {
-    calculateLayout(_constraints: BoxConstraints, _offset: Offset, _ctx: LayoutContext): Size;
+    /** 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;
     isPageBreak(): boolean;
     hasForcedBreak(): boolean;
     getProps(): Record<string, never>;

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

@@ -1,4 +1,5 @@
 import { PDFElement } from "../pdf-element.js";
+import { pageOf } from "../../common/diagnostics.js";
 /**
  * A forced page break. Placed in a flow (a `Column`/`Row`/`Box`), it makes everything AFTER it start
  * on a fresh page, no matter how much space is left. It takes zero space and draws nothing - the
@@ -9,7 +10,11 @@ import { PDFElement } from "../pdf-element.js";
  * too. A break wins over a `keepTogether` (a forced break cannot be avoided) - CSS behaves the same.
  */
 export class PageBreakElement extends PDFElement {
-    calculateLayout(_constraints, _offset, _ctx) {
+    calculateLayout(_constraints, _offset, ctx) {
+        this.page = pageOf(ctx);
+        return { width: 0, height: 0 };
+    }
+    computeSize() {
         return { width: 0, height: 0 };
     }
     isPageBreak() {

package/dist/elements/layout/page-builder-element.d.ts

@@ -26,6 +26,11 @@ export declare class PageBuilderElement extends PDFElement {
     /** The real page info during the render pass; a provisional "1 of 1" while paginating. */
     private infoFrom;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /** It is built from the page it lands on. */
+    dependsOnPage(): boolean;
+    /** Builds a throwaway subtree to size it; only a real layout keeps what it built. */
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    layoutChildren(): readonly PDFElement[];
     getProps(): {
         composed: PDFElement | undefined;
     };

package/dist/elements/layout/page-builder-element.js

@@ -36,9 +36,20 @@ export class PageBuilderElement extends PDFElement {
         this.composed = this.build(this.infoFrom(ctx));
         return this.composed.calculateLayout(constraints, offset, ctx);
     }
+    /** It is built from the page it lands on. */
+    dependsOnPage() {
+        return true;
+    }
+    /** Builds a throwaway subtree to size it; only a real layout keeps what it built. */
+    computeSize(constraints, ctx) {
+        return this.build(this.infoFrom(ctx)).measure(constraints, ctx);
+    }
     // Named `composed` (not `child`) like DeferredElement: the pre-layout image walk keys on `child`, and
-    // this subtree does not exist yet when it runs. So an Image inside a PageBuilder skips aspect-ratio
-    // pre-resolution - give it both width and height, exactly as inside a Deferred/Table subtree.
+    // this subtree does not exist yet when it runs. An Image built here reads its own size when layout
+    // asks; only one from a URL cannot, and reports `image-unsized`.
+    layoutChildren() {
+        return this.composed ? [this.composed] : [];
+    }
     getProps() {
         return { composed: this.composed };
     }

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

@@ -11,6 +11,9 @@ export type PositionAnchor = "start" | "center" | "end";
  * An edge wins over an anchor on the same axis. With nothing set the child sits at the top-left.
  */
 export interface PositionedInsets {
+    /** Paint order within its stacking context: negative under the flow content, positive over it,
+     *  higher over lower; 0 or unset paints in tree order where it stands (CSS `z-index`). */
+    zIndex?: number;
     top?: number;
     right?: number;
     bottom?: number;
@@ -38,10 +41,26 @@ interface PositionedElementParams extends WithChild, PositionedInsets {
 export declare class PositionedElement extends PDFElement {
     private child;
     private insets;
-    constructor({ child, top, right, bottom, left, h, v, x, y }: PositionedElementParams);
+    private placeCtx?;
+    constructor({ child, top, right, bottom, left, h, v, x, y, zIndex }: PositionedElementParams);
+    /** Its paint order; 0 paints where it stands in the tree, anything else is sorted by its context. */
+    private readonly zIndex;
     calculateLayout(_constraints: BoxConstraints, _offset: Offset, ctx: LayoutContext): Size;
-    /** Lays the child out at the resolved position inside (or overflowing) the frame box. */
-    private placeInFrame;
-    getProps(): WithChild;
+    /** Out of flow: it takes no room, and measuring registers nothing with the frame. */
+    protected computeSize(): Size;
+    layoutChildren(): readonly PDFElement[];
+    /**
+     * Lays the child out at the resolved position inside (or overflowing) a frame of `frameSize`. The
+     * offset is relative to the frame's top-left; its owner draws the child from there.
+     */
+    placeIn(frameSize: Size, frameCtx: LayoutContext): void;
+    getProps(): WithChild & {
+        zIndex: number;
+    };
 }
+/**
+ * The `Positioned` elements a frame owns, in tree order: every one below `roots`, including those
+ * inside another `Positioned`, but none below a nested frame - that one places its own.
+ */
+export declare function positionedIn(roots: readonly (PDFElement | undefined)[]): PositionedElement[];
 export {};

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

@@ -14,22 +14,38 @@ import { PDFElement } from "../pdf-element.js";
  * (ISSUE-4). Content that lands somewhere unasked is worse than content that does not render.
  */
 export class PositionedElement extends PDFElement {
-    constructor({ child, top, right, bottom, left, h, v, x, y }) {
+    constructor({ child, top, right, bottom, left, h, v, x, y, zIndex }) {
         super();
+        if (zIndex !== undefined && !Number.isFinite(zIndex)) {
+            throw new Error(`Invalid zIndex ${zIndex}: it must be a number.`);
+        }
         this.child = child;
         this.insets = { top, right, bottom, left, h, v, x, y };
+        this.zIndex = zIndex ?? 0;
     }
     calculateLayout(_constraints, _offset, ctx) {
         if (!ctx.frame) {
             throw new Error("Positioned found no positioning frame. It must sit inside a Page (header, footer or body) " +
                 "or inside a Box({ relative: true }).");
         }
-        // Defer to the frame: it calls back once it has sized itself. Out of flow either way.
-        ctx.frame.place.push((frame, frameCtx) => this.placeInFrame(frame, frameCtx));
+        // Out of flow: it takes no room here. The frame's owner places it once it knows its own size.
+        this.placeCtx = ctx;
+        return { width: 0, height: 0 };
+    }
+    /** Out of flow: it takes no room, and measuring registers nothing with the frame. */
+    computeSize() {
         return { width: 0, height: 0 };
     }
-    /** Lays the child out at the resolved position inside (or overflowing) the frame box. */
-    placeInFrame(frame, ctx) {
+    layoutChildren() {
+        return [this.child];
+    }
+    /**
+     * Lays the child out at the resolved position inside (or overflowing) a frame of `frameSize`. The
+     * offset is relative to the frame's top-left; its owner draws the child from there.
+     */
+    placeIn(frameSize, frameCtx) {
+        const ctx = this.placeCtx ?? frameCtx;
+        const frame = { origin: { x: 0, y: 0 }, size: frameSize };
         const { top, right, bottom, left, h, v, x: nudgeX, y: nudgeY } = this.insets;
         // An axis is PINNED (stretched) only when BOTH of its EDGES are given; otherwise the child
         // shrink-wraps its content (unbounded), the CSS rule for an absolutely-positioned element. An
@@ -42,12 +58,7 @@ export class PositionedElement extends PDFElement {
             : Infinity;
         const constraints = BoxConstraints.loose(width, height);
         // Measure first (so end/center anchors and right/bottom edges resolve against the child's size).
-        // The measuring pass gets a throwaway `place` list: this subtree is laid out twice, and a nested
-        // out-of-flow child would otherwise register its placement on both passes.
-        const measureCtx = ctx.frame
-            ? { ...ctx, frame: { ...ctx.frame, place: [] } }
-            : ctx;
-        const measured = this.child.calculateLayout(constraints, { x: 0, y: 0 }, measureCtx);
+        const measured = this.child.measure(constraints, ctx);
         // Resolve one axis: a near-edge pins to origin, a far-edge pins to the far side; otherwise the
         // anchor (default `start`) positions the child and the nudge shifts it from there.
         const place = (origin, frameExtent, childExtent, nearEdge, farEdge, anchor, nudge) => {
@@ -68,6 +79,25 @@ export class PositionedElement extends PDFElement {
         this.child.calculateLayout(constraints, { x, y }, ctx);
     }
     getProps() {
-        return { child: this.child };
+        return { child: this.child, zIndex: this.zIndex };
     }
 }
+/**
+ * The `Positioned` elements a frame owns, in tree order: every one below `roots`, including those
+ * inside another `Positioned`, but none below a nested frame - that one places its own.
+ */
+export function positionedIn(roots) {
+    const found = [];
+    const walk = (el) => {
+        if (el instanceof PositionedElement)
+            found.push(el);
+        if (el.isPositioningFrame())
+            return;
+        for (const child of el.layoutChildren())
+            walk(child);
+    };
+    for (const root of roots)
+        if (root)
+            walk(root);
+    return found;
+}

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

@@ -0,0 +1,47 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
+import { LayoutContext, PDFElement } from "../pdf-element.js";
+/**
+ * A wrapper that is transparent to layout (Flutter's `RenderProxyBox`): its one child gets the same
+ * constraints, sits at the same offset and gives the same size. Every sizing and pagination signal the
+ * child sends is passed on, so wrapping something never changes how it is sized or broken across
+ * pages - a `PageBreak` inside a `Link` breaks, a `Bookmark` around a chapter splits like the chapter.
+ *
+ * What a wrapper adds (a link, a jump target, a role, inherited text defaults) it adds through two
+ * hooks: `childContext` for what the child is laid out in, and `rewrap` for the pieces of a split.
+ */
+export declare abstract class ProxyElement extends PDFElement implements Fragmentable {
+    protected readonly child: PDFElement;
+    protected x: number;
+    protected y: number;
+    protected width: number;
+    protected height: number;
+    protected constructor(child: PDFElement);
+    /** The context the child is laid out in: unchanged, unless the wrapper hands something down. */
+    protected childContext(ctx: LayoutContext): LayoutContext;
+    /**
+     * This wrapper around a piece of its split child. `continued` is true for every piece but the first
+     * one that holds something: a wrapper that marks a single place (a jump target, an outline entry)
+     * returns the piece bare there, so the mark is not repeated on the next page.
+     */
+    protected abstract rewrap(child: PDFElement, continued: boolean): PDFElement;
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    layoutChildren(): readonly PDFElement[];
+    /** Transparent to a surrounding Row or Column too: it sees the child's flex properties. */
+    proxiedContext(ctx: LayoutContext): LayoutContext;
+    proxied(): PDFElement;
+    relativeSizeFactor(horizontal: boolean): number | undefined;
+    maxExtent(horizontal: boolean): number;
+    needsBoundedMain(horizontal: boolean): boolean;
+    minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
+    needsRegion(): boolean;
+    isPageBreak(): boolean;
+    isColumnBreak(): boolean;
+    hasForcedBreak(): boolean;
+    breaksBefore(): boolean;
+    breaksAfter(): boolean;
+    /** Splittable exactly when the child is; otherwise the parent moves it to the next page whole. */
+    canFragment(): boolean;
+    fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+}

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

@@ -0,0 +1,106 @@
+import { BoxConstraints } from "../../layout/box-constraints.js";
+import { isFragmentable } from "../../layout/fragmentation.js";
+import { PDFElement } from "../pdf-element.js";
+/**
+ * A wrapper that is transparent to layout (Flutter's `RenderProxyBox`): its one child gets the same
+ * constraints, sits at the same offset and gives the same size. Every sizing and pagination signal the
+ * child sends is passed on, so wrapping something never changes how it is sized or broken across
+ * pages - a `PageBreak` inside a `Link` breaks, a `Bookmark` around a chapter splits like the chapter.
+ *
+ * What a wrapper adds (a link, a jump target, a role, inherited text defaults) it adds through two
+ * hooks: `childContext` for what the child is laid out in, and `rewrap` for the pieces of a split.
+ */
+export class ProxyElement extends PDFElement {
+    constructor(child) {
+        super();
+        this.child = child;
+        // The box the child took, for renderers that mark it (a link's hit area, a jump target's top).
+        this.x = 0;
+        this.y = 0;
+        this.width = 0;
+        this.height = 0;
+    }
+    /** The context the child is laid out in: unchanged, unless the wrapper hands something down. */
+    childContext(ctx) {
+        return ctx;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        const size = this.child.calculateLayout(constraints, offset, this.childContext(ctx));
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = size.width;
+        this.height = size.height;
+        return size;
+    }
+    computeSize(constraints, ctx) {
+        return this.child.measure(constraints, this.childContext(ctx));
+    }
+    layoutChildren() {
+        return [this.child];
+    }
+    /** Transparent to a surrounding Row or Column too: it sees the child's flex properties. */
+    proxiedContext(ctx) {
+        return this.childContext(ctx);
+    }
+    proxied() {
+        return this.child;
+    }
+    relativeSizeFactor(horizontal) {
+        return this.child.relativeSizeFactor(horizontal);
+    }
+    maxExtent(horizontal) {
+        return this.child.maxExtent(horizontal);
+    }
+    needsBoundedMain(horizontal) {
+        return this.child.needsBoundedMain(horizontal);
+    }
+    minIntrinsicMain(horizontal, ctx) {
+        return this.child.minIntrinsicMain(horizontal, this.childContext(ctx));
+    }
+    needsRegion() {
+        return this.child.needsRegion();
+    }
+    isPageBreak() {
+        return this.child.isPageBreak();
+    }
+    isColumnBreak() {
+        return this.child.isColumnBreak();
+    }
+    hasForcedBreak() {
+        return this.child.hasForcedBreak();
+    }
+    breaksBefore() {
+        return this.child.breaksBefore();
+    }
+    breaksAfter() {
+        return this.child.breaksAfter();
+    }
+    /** Splittable exactly when the child is; otherwise the parent moves it to the next page whole. */
+    canFragment() {
+        return isFragmentable(this.child);
+    }
+    fragment(maxHeight, width, ctx) {
+        if (!isFragmentable(this.child))
+            return { fitted: null, remainder: this };
+        const childCtx = this.childContext(ctx);
+        const split = this.child.fragment(maxHeight, width, childCtx);
+        // The child handed itself back (it all fits, or none of it does): so does the wrapper, mark included.
+        const wrap = (piece, continued) => {
+            if (piece === this.child)
+                return this;
+            const wrapped = this.rewrap(piece, continued);
+            // A wrapper dropped from a continued piece still leaves that piece in its place in the flow.
+            return wrapped === piece ? piece.takeFlexItemFrom(this) : wrapped.asPieceOf(this);
+        };
+        // A fitted piece with no height (what a leading `PageBreak` leaves) holds nothing to mark: the
+        // mark goes on with the remainder, where the content is.
+        const placed = split.fitted !== null &&
+            (split.remainder === null ||
+                split.fitted.measure(BoxConstraints.loose(width, Infinity), childCtx).height > 0);
+        return {
+            fitted: split.fitted && wrap(split.fitted, !placed),
+            remainder: split.remainder && wrap(split.remainder, placed),
+            forceBreak: split.forceBreak,
+        };
+    }
+}

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

@@ -0,0 +1,53 @@
+import { BoxConstraints, Offset, Size, SizingParams } from "../../layout/box-constraints.js";
+import { LayoutContext, PDFElement, SizedPDFElement } from "../pdf-element.js";
+interface RegionElementParams extends SizingParams {
+    widthFactor?: number;
+    heightFactor?: number;
+}
+/** A `Region` was laid out somewhere no `Flow` claimed it: outside a template, or inside the content. */
+export declare class RegionOutsideFlowError extends Error {
+    constructor();
+}
+/** One Region instance handed to two pages of a Flow (or two Flows): both would draw the same content. */
+export declare class RegionReusedError extends Error {
+    constructor();
+}
+/**
+ * A place in a `Flow`'s template that the content flows through. It has no size of its own: the layout
+ * around it sizes it (`Expanded`, `width`, `height`, `%`), and with nothing given it fills what it is
+ * offered, as a Canvas does. The Flow claims it, then hands it the piece of content that fits.
+ */
+export declare class RegionElement extends SizedPDFElement {
+    private requested;
+    private sizing;
+    private widthFactor?;
+    private heightFactor?;
+    private owner?;
+    private content;
+    constructor(params?: RegionElementParams);
+    /** Marks it as part of one page of a Flow; a second page claiming it throws. */
+    private claim;
+    /** The content it holds on this page (`null`: the content ran out before it). */
+    hold(content: PDFElement | null): void;
+    get held(): PDFElement | null;
+    /** A height the author gave (points or `%`): kept on the Flow's last page instead of shrinking. */
+    hasOwnHeight(): boolean;
+    /** Where it has no size of its own it fills what it is offered, so the stack around it must offer
+     *  something - as for a Spacer. */
+    needsBoundedMain(horizontal: boolean): boolean;
+    /** A `%` size is a share of the stack it sits in, which has to know to resolve it - as for a Box. */
+    relativeSizeFactor(horizontal: boolean): number | 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;
+    layoutChildren(): readonly PDFElement[];
+    getProps(): {
+        child?: PDFElement | undefined;
+        x: number;
+        y: number;
+        width: number | undefined;
+        height: number | undefined;
+    };
+}
+export {};

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

@@ -0,0 +1,108 @@
+import { BoxConstraints, extentSpecs, resolveSize, } from "../../layout/box-constraints.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/** A `Region` was laid out somewhere no `Flow` claimed it: outside a template, or inside the content. */
+export class RegionOutsideFlowError extends Error {
+    constructor() {
+        super("@jasy/pdf: a Region only means something in a Flow's template - it marks where the content " +
+            "flows. Put it in the template (in @jasy/vue: the #page slot), not in the content or anywhere else.");
+        this.name = "RegionOutsideFlowError";
+    }
+}
+/** One Region instance handed to two pages of a Flow (or two Flows): both would draw the same content. */
+export class RegionReusedError extends Error {
+    constructor() {
+        super("@jasy/pdf: a Region is used by two pages of a Flow (or by two Flows). A template is called for " +
+            "every page - build the Regions, and the layout around them, inside the function.");
+        this.name = "RegionReusedError";
+    }
+}
+/**
+ * A place in a `Flow`'s template that the content flows through. It has no size of its own: the layout
+ * around it sizes it (`Expanded`, `width`, `height`, `%`), and with nothing given it fills what it is
+ * offered, as a Canvas does. The Flow claims it, then hands it the piece of content that fits.
+ */
+export class RegionElement extends SizedPDFElement {
+    constructor(params = {}) {
+        super({ x: 0, y: 0, width: params.width, height: params.height });
+        this.content = null;
+        const { widthFactor, heightFactor, ...sizing } = params;
+        this.widthFactor = widthFactor;
+        this.heightFactor = heightFactor;
+        this.sizing = sizing;
+        this.requested = { width: params.width, height: params.height };
+    }
+    /** Marks it as part of one page of a Flow; a second page claiming it throws. */
+    claim(owner) {
+        if (this.owner && this.owner !== owner)
+            throw new RegionReusedError();
+        this.owner = owner;
+    }
+    /** The content it holds on this page (`null`: the content ran out before it). */
+    hold(content) {
+        this.content = content;
+    }
+    get held() {
+        return this.content;
+    }
+    /** A height the author gave (points or `%`): kept on the Flow's last page instead of shrinking. */
+    hasOwnHeight() {
+        return this.requested.height !== undefined || this.heightFactor !== undefined;
+    }
+    /** Where it has no size of its own it fills what it is offered, so the stack around it must offer
+     *  something - as for a Spacer. */
+    needsBoundedMain(horizontal) {
+        return horizontal
+            ? this.requested.width === undefined && this.widthFactor === undefined
+            : !this.hasOwnHeight();
+    }
+    /** A `%` size is a share of the stack it sits in, which has to know to resolve it - as for a Box. */
+    relativeSizeFactor(horizontal) {
+        return horizontal ? this.widthFactor : this.heightFactor;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        // Laid out in a Flow's template, it belongs to that page; anywhere else it has no meaning.
+        if (!ctx.flowPage)
+            throw new RegionOutsideFlowError();
+        this.claim(ctx.flowPage);
+        const size = this.sizeFor(constraints);
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = size.width;
+        this.height = size.height;
+        // Its content is not the template: a Region in it is outside any Flow (or in its own inner one).
+        this.content?.calculateLayout(BoxConstraints.loose(size.width, size.height), { x: 0, y: 0 }, { ...ctx, flowPage: undefined });
+        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,
+            height: this.requested.height,
+            widthFactor: this.widthFactor,
+            heightFactor: this.heightFactor,
+        });
+        const resolved = resolveSize(specs.width, specs.height, this.sizing.aspectRatio, constraints);
+        const bounds = resolved.constraints;
+        return {
+            width: resolved.width ?? (bounds.hasBoundedWidth ? bounds.maxWidth : 0),
+            height: resolved.height ?? (bounds.hasBoundedHeight ? bounds.maxHeight : 0),
+        };
+    }
+    layoutChildren() {
+        return this.content ? [this.content] : [];
+    }
+    getProps() {
+        return {
+            x: this.x,
+            y: this.y,
+            width: this.width,
+            height: this.height,
+            // Only when it holds something: the pre-layout walks read `child` as an element.
+            ...(this.content ? { child: this.content } : {}),
+        };
+    }
+}