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

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

@@ -14,10 +14,14 @@ 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) {
@@ -75,7 +79,7 @@ export class PositionedElement extends PDFElement {
         this.child.calculateLayout(constraints, { x, y }, ctx);
     }
     getProps() {
-        return { child: this.child };
+        return { child: this.child, zIndex: this.zIndex };
     }
 }
 /**

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

@@ -29,11 +29,15 @@ export declare abstract class ProxyElement extends PDFElement implements Fragmen
     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;

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

@@ -39,21 +39,33 @@ export class ProxyElement extends PDFElement {
         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();
     }

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,109 @@
+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; in @jasy/react: the page prop), 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 } : {}),
+        };
+    }
+}

package/dist/elements/layout/repeating-header-element.d.ts

@@ -16,6 +16,9 @@ export declare class RepeatingHeaderElement extends PDFElement implements Fragme
     private width;
     private height;
     constructor(header: PDFElement, body: PDFElement, gap?: number);
+    /** The header for the next piece: a copy, since two pieces may share a page (two Regions of a Flow)
+     *  and one element has one position - that tags as the SAME header. */
+    private nextHeader;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
     /** The one sizing path: `layout` places header and body (relative to this box), `measure` sizes. */

package/dist/elements/layout/repeating-header-element.js

@@ -1,6 +1,14 @@
 import { BoxConstraints } from "../../layout/box-constraints.js";
 import { insetContext, isFragmentable, } from "../../layout/fragmentation.js";
 import { PDFElement } from "../pdf-element.js";
+/** Gives every element of `fresh` the tagging identity of its twin in `from` (the same shape). */
+function adoptStructIds(fresh, from) {
+    fresh.adoptStructId(from);
+    const a = fresh.layoutChildren();
+    const b = from.layoutChildren();
+    for (let i = 0; i < a.length && i < b.length; i++)
+        adoptStructIds(a[i], b[i]);
+}
 /**
  * Stacks a `header` above a `body` and, when it paginates, **repeats the header on every
  * fragment**. Used by `Table` so column headings reappear at the top of each page. Layout
@@ -18,6 +26,13 @@ export class RepeatingHeaderElement extends PDFElement {
         this.width = 0;
         this.height = 0;
     }
+    /** The header for the next piece: a copy, since two pieces may share a page (two Regions of a Flow)
+     *  and one element has one position - that tags as the SAME header. */
+    nextHeader() {
+        const copy = this.header.clone();
+        adoptStructIds(copy, this.header);
+        return copy;
+    }
     calculateLayout(constraints, offset, ctx) {
         const size = this.sizeWith(constraints, ctx, "layout");
         this.x = offset.x;
@@ -58,7 +73,7 @@ export class RepeatingHeaderElement extends PDFElement {
                 ? new RepeatingHeaderElement(this.header, split.fitted, this.gap).asPieceOf(this)
                 : null,
             remainder: split.remainder
-                ? new RepeatingHeaderElement(this.header, split.remainder, this.gap).asPieceOf(this)
+                ? new RepeatingHeaderElement(this.nextHeader(), split.remainder, this.gap).asPieceOf(this)
                 : null,
             forceBreak: split.forceBreak,
         };

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

@@ -23,7 +23,9 @@ export declare class RotatedElement extends PDFElement {
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
     layoutChildren(): readonly PDFElement[];
+    proxied(): PDFElement;
     relativeSizeFactor(horizontal: boolean): number | undefined;
+    maxExtent(horizontal: boolean): number;
     needsBoundedMain(horizontal: boolean): boolean;
     minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
     breaksBefore(): boolean;

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

@@ -34,11 +34,19 @@ export class RotatedElement extends PDFElement {
     layoutChildren() {
         return [this.child];
     }
+    // The spin is paint-only, so to a surrounding Row or Column the child is the item (CSS: a `transform`
+    // leaves an item an item).
+    proxied() {
+        return this.child;
+    }
     // It takes the child's space, so the child's sizing hints and its break-before/after are its own.
     // It is never split - half a rotation on each page means nothing - so a break INSIDE stays inside.
     relativeSizeFactor(horizontal) {
         return this.child.relativeSizeFactor(horizontal);
     }
+    maxExtent(horizontal) {
+        return this.child.maxExtent(horizontal);
+    }
     needsBoundedMain(horizontal) {
         return this.child.needsBoundedMain(horizontal);
     }

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

@@ -74,10 +74,17 @@ export interface LayoutContext {
      *  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;
-    /** What a `Box`'s percentage padding resolves against: the width the Box itself was offered (CSS:
-     *  the containing block), not its inner width. Set by the Box for its own padding only. */
+    /** 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;
@@ -130,6 +137,12 @@ export declare abstract class PDFElement {
      * `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[];
     /**
@@ -137,6 +150,11 @@ export declare abstract class PDFElement {
      * 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;
     /**
@@ -146,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
@@ -165,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;

package/dist/elements/pdf-element.js

@@ -1,4 +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() {
@@ -67,6 +71,25 @@ export class PDFElement {
     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 [];
@@ -78,6 +101,15 @@ export class PDFElement {
     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;
@@ -91,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
@@ -114,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.
@@ -121,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,15 +74,18 @@ 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;
-    /** A Box's own padding resolves a percentage against what the Box was OFFERED (CSS: the containing
-     *  block), not against the inner width it hands its children - so it is told. Only a bounded offer:
-     *  in a Row a child is offered no width at all, and there the padding keeps resolving against the
-     *  Box's own width, as it always did. */
+    /** 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;
@@ -93,6 +96,9 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
      */
     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;

package/dist/elements/rectangle-element.js

@@ -4,8 +4,8 @@ import { BoxConstraints, extentSpecs, resolveSize, } from "../layout/box-constra
 import { stackMinIntrinsic, withDeclaredExtent } from "../layout/min-intrinsic.js";
 import { positionedIn } from "./layout/positioned-element.js";
 import { PaddingElement } from "./layout/padding-element.js";
-import { childrenForceBreak, insetContext, packChildren, } from "../layout/fragmentation.js";
-import { SizedPDFElement, } from "./pdf-element.js";
+import { childrenForceBreak, insetContext, packChildren, packedUnchanged, } from "../layout/fragmentation.js";
+import { SizedPDFElement, withPaddingBase, } from "./pdf-element.js";
 export class RectangleElement extends SizedPDFElement {
     constructor({ children = [], color = new Color(0, 0, 0), backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, breakBefore, breakAfter, ...sizing }) {
         super({ x: 0, y: 0, width, height });
@@ -51,7 +51,7 @@ export class RectangleElement extends SizedPDFElement {
         // Fits with no forced cut: return the whole box unchanged. A trailing forced break is the
         // exception - fall through so the box is rebuilt from the packed children (without the consumed
         // break marker), rather than handing back the original that still holds it.
-        if (remainder.length === 0 && !forceBreak) {
+        if (remainder.length === 0 && !forceBreak && packedUnchanged(this.children, fitted)) {
             // The content fits, but a fixed height may not - such a box cannot shrink, so it moves on whole.
             const own = this.measure(BoxConstraints.loose(width, Infinity), ctx).height;
             return own <= maxHeight
@@ -67,10 +67,12 @@ export class RectangleElement extends SizedPDFElement {
             fitted: this.cloneWithChildren(fitted, contentHeight(fitted) + 2 * this.borderWidth),
             // A trailing forced break leaves nothing to carry over: no remainder box, no extra page.
             // Only the CONTINUATION carries `breakAfter` (a box that splits still breaks after its LAST
-            // fragment, not its first); `breakBefore` is dropped, already honoured before the split.
+            // fragment, not its first); `breakBefore` is dropped, already honored before the split.
+            // It gets no height, as a Column's piece does: it is sized where it lands, which may be a
+            // narrower or wider region (a Flow's), or one that gives a region-sized rest its height.
             remainder: remainder.length === 0
                 ? null
-                : this.cloneWithChildren(remainder, contentHeight(remainder) + 2 * this.borderWidth, this.breakAfter),
+                : this.cloneWithChildren(remainder, undefined, this.breakAfter),
             forceBreak,
         };
     }
@@ -99,6 +101,9 @@ export class RectangleElement extends SizedPDFElement {
     relativeSizeFactor(horizontal) {
         return horizontal ? this.sizeMemory.widthFactor : this.sizeMemory.heightFactor;
     }
+    maxExtent(horizontal) {
+        return (horizontal ? this.sizeMemory.maxWidth : this.sizeMemory.maxHeight) ?? Infinity;
+    }
     /** 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. */
@@ -110,15 +115,24 @@ export class RectangleElement extends SizedPDFElement {
             return false;
         return this.children.some((c) => c.needsBoundedMain(horizontal));
     }
-    /** A Box's own padding resolves a percentage against what the Box was OFFERED (CSS: the containing
-     *  block), not against the inner width it hands its children - so it is told. Only a bounded offer:
-     *  in a Row a child is offered no width at all, and there the padding keeps resolving against the
-     *  Box's own width, as it always did. */
+    /** As a Column: a height of its own is the region; without one, a region-sized child needs the page's. */
+    needsRegion() {
+        if (this.sizeMemory.height !== undefined || this.sizeMemory.heightFactor !== undefined) {
+            return false;
+        }
+        return this.children.some((c) => c.needsRegion());
+    }
+    /** 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. */
     paddingContext(ctx, offered) {
+        if (!this.hasPercentPadding())
+            return withPaddingBase(ctx, undefined);
+        return withPaddingBase(ctx, ctx.boxPaddingBase ?? (Number.isFinite(offered) ? offered : undefined));
+    }
+    hasPercentPadding() {
         const own = this.children[0];
-        return own instanceof PaddingElement && own.ofBox && Number.isFinite(offered)
-            ? { ...ctx, boxPaddingBase: offered }
-            : ctx;
+        return own instanceof PaddingElement && own.ofBox && own.hasPercentSide;
     }
     /** A Box stacks its children vertically inside its border, which is on both sides of the axis. */
     minIntrinsicMain(horizontal, ctx) {
@@ -242,6 +256,11 @@ export class RectangleElement extends SizedPDFElement {
     isPositioningFrame() {
         return this.relative;
     }
+    /** 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() {
+        return this.relative || this.overflow === "hidden";
+    }
     layoutChildren() {
         return this.children ?? [];
     }