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

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

@@ -0,0 +1,32 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, PageInfo, PDFElement } from "../pdf-element.js";
+/**
+ * Builds its subtree from the page it lands on, so a header, a footer or plain body content can show
+ * `pageNumber` / `pageCount`. The closure runs on EVERY layout, because the numbers differ between the
+ * two driver passes: pagination has to size the element before the page total exists, so it builds
+ * against a provisional "1 of 1"; the render pass then rebuilds it with the real `PageInfo`.
+ *
+ * Two consequences, and neither is magic - both come from the same chicken-and-egg: the content decides
+ * the page count that the content displays.
+ *
+ * 1. In the flowing BODY the box is reserved by the provisional build, so a much wider final string
+ *    (`"9 of 10"` vs `"1 of 1"`) can paint slightly past it. Keep dynamic body content roughly constant
+ *    in width.
+ * 2. A header/footer is re-laid out per page, so its real height is honoured - but the BODY band was
+ *    already sized against the provisional build. A later page whose header is SHORTER simply gains
+ *    room (harmless). A later page whose header is TALLER shrinks the band its body was measured for,
+ *    and that body can overflow. So: a conditional header may shrink on later pages, never grow.
+ */
+export declare class PageBuilderElement extends PDFElement {
+    private composed?;
+    private readonly build;
+    constructor({ build }: {
+        build: (info: PageInfo) => 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;
+    getProps(): {
+        composed: PDFElement | undefined;
+    };
+}

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

@@ -0,0 +1,43 @@
+import { PDFElement } from "../pdf-element.js";
+import { resolvePageSize } from "../page-element.js";
+/**
+ * Builds its subtree from the page it lands on, so a header, a footer or plain body content can show
+ * `pageNumber` / `pageCount`. The closure runs on EVERY layout, because the numbers differ between the
+ * two driver passes: pagination has to size the element before the page total exists, so it builds
+ * against a provisional "1 of 1"; the render pass then rebuilds it with the real `PageInfo`.
+ *
+ * Two consequences, and neither is magic - both come from the same chicken-and-egg: the content decides
+ * the page count that the content displays.
+ *
+ * 1. In the flowing BODY the box is reserved by the provisional build, so a much wider final string
+ *    (`"9 of 10"` vs `"1 of 1"`) can paint slightly past it. Keep dynamic body content roughly constant
+ *    in width.
+ * 2. A header/footer is re-laid out per page, so its real height is honoured - but the BODY band was
+ *    already sized against the provisional build. A later page whose header is SHORTER simply gains
+ *    room (harmless). A later page whose header is TALLER shrinks the band its body was measured for,
+ *    and that body can overflow. So: a conditional header may shrink on later pages, never grow.
+ */
+export class PageBuilderElement extends PDFElement {
+    constructor({ build }) {
+        super();
+        this.build = build;
+    }
+    /** The real page info during the render pass; a provisional "1 of 1" while paginating. */
+    infoFrom(ctx) {
+        return (ctx.pageInfo ?? {
+            pageNumber: 1,
+            pageCount: 1,
+            pageSize: resolvePageSize(ctx.pageConfig),
+        });
+    }
+    calculateLayout(constraints, offset, ctx) {
+        this.composed = this.build(this.infoFrom(ctx));
+        return this.composed.calculateLayout(constraints, offset, 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.
+    getProps() {
+        return { composed: this.composed };
+    }
+}

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

@@ -0,0 +1,35 @@
+import { PDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+/**
+ * Rotates its child by whole quarter-turns and, unlike `RotatedElement` (paint-only), makes the
+ * rotation LAYOUT-AWARE: for a 90 / 270 turn it SWAPS width and height, so the box reports the rotated
+ * footprint UP and siblings reflow around it. A tall text becomes a narrow vertical strip that actually
+ * reserves its narrow width and its long height - the "vertical label beside a table" case.
+ *
+ * `turns` is the number of 90-degree CLOCKWISE quarter-turns (like Flutter's `RotatedBox.quarterTurns`):
+ * 0 = none, 1 = 90, 2 = 180, 3 = 270. The child lays out with the box's constraints swapped, then it is
+ * placed centered on the box's center so a plain center-rotation (the shared renderer) maps it exactly
+ * onto the swapped box.
+ */
+export declare class RotatedBoxElement extends PDFElement {
+    private turns;
+    private child;
+    private x;
+    private y;
+    private width;
+    private height;
+    constructor({ turns, child }: {
+        turns: number;
+        child: PDFElement;
+    });
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /** Same shape as `RotatedElement` (angle + box), so both share `RotatedRenderer`. */
+    getProps(): {
+        angle: number;
+        child: PDFElement;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}

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

@@ -0,0 +1,54 @@
+import { PDFElement } from "../pdf-element.js";
+import { BoxConstraints } from "../../layout/box-constraints.js";
+/**
+ * Rotates its child by whole quarter-turns and, unlike `RotatedElement` (paint-only), makes the
+ * rotation LAYOUT-AWARE: for a 90 / 270 turn it SWAPS width and height, so the box reports the rotated
+ * footprint UP and siblings reflow around it. A tall text becomes a narrow vertical strip that actually
+ * reserves its narrow width and its long height - the "vertical label beside a table" case.
+ *
+ * `turns` is the number of 90-degree CLOCKWISE quarter-turns (like Flutter's `RotatedBox.quarterTurns`):
+ * 0 = none, 1 = 90, 2 = 180, 3 = 270. The child lays out with the box's constraints swapped, then it is
+ * placed centered on the box's center so a plain center-rotation (the shared renderer) maps it exactly
+ * onto the swapped box.
+ */
+export class RotatedBoxElement extends PDFElement {
+    constructor({ turns, child }) {
+        super();
+        this.x = 0;
+        this.y = 0;
+        this.width = 0;
+        this.height = 0;
+        this.turns = ((Math.trunc(turns) % 4) + 4) % 4;
+        this.child = child;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        const quarter = this.turns % 2 === 1; // 90 or 270: axes swap
+        // A quarter-turned child experiences the box's constraints with the axes swapped.
+        const childConstraints = quarter
+            ? new BoxConstraints(constraints.minHeight, constraints.maxHeight, constraints.minWidth, constraints.maxWidth)
+            : constraints;
+        // Measure the child to learn its natural size, then take that size swapped as our own box.
+        const child = this.child.calculateLayout(childConstraints, offset, ctx);
+        this.width = quarter ? child.height : child.width;
+        this.height = quarter ? child.width : child.height;
+        this.x = offset.x;
+        this.y = offset.y;
+        // Re-place the child CENTERED on the box center: a rotation around that center then maps the
+        // child's (w x h) box exactly onto our (swapped) box - so the shared renderer needs no special case.
+        const cx = this.x + this.width / 2;
+        const cy = this.y + this.height / 2;
+        this.child.calculateLayout(childConstraints, { x: cx - child.width / 2, y: cy - child.height / 2 }, ctx);
+        return { width: this.width, height: this.height };
+    }
+    /** Same shape as `RotatedElement` (angle + box), so both share `RotatedRenderer`. */
+    getProps() {
+        return {
+            angle: this.turns * 90,
+            child: this.child,
+            x: this.x,
+            y: this.y,
+            width: this.width,
+            height: this.height,
+        };
+    }
+}

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

@@ -0,0 +1,32 @@
+import { PDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+/**
+ * Rotates its single child at PAINT time only (like Flutter's `Transform.rotate`): the child lays out
+ * in its normal, axis-aligned box and the element reports that same box UP, so siblings never reflow
+ * around the rotated shape. Only the drawing is rotated, around the box's center, by the renderer.
+ *
+ * Layout-transparent: it delegates `calculateLayout` to the child and just records the resulting box,
+ * which the renderer needs as the pivot. Not `Fragmentable` on purpose - a rotated subtree is atomic
+ * w.r.t. pagination (it moves whole to the next page rather than splitting mid-rotation).
+ */
+export declare class RotatedElement extends PDFElement {
+    private angle;
+    private child;
+    private x;
+    private y;
+    private width;
+    private height;
+    constructor({ angle, child }: {
+        angle: number;
+        child: PDFElement;
+    });
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    getProps(): {
+        angle: number;
+        child: PDFElement;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}

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

@@ -0,0 +1,41 @@
+import { PDFElement } from "../pdf-element.js";
+/**
+ * Rotates its single child at PAINT time only (like Flutter's `Transform.rotate`): the child lays out
+ * in its normal, axis-aligned box and the element reports that same box UP, so siblings never reflow
+ * around the rotated shape. Only the drawing is rotated, around the box's center, by the renderer.
+ *
+ * Layout-transparent: it delegates `calculateLayout` to the child and just records the resulting box,
+ * which the renderer needs as the pivot. Not `Fragmentable` on purpose - a rotated subtree is atomic
+ * w.r.t. pagination (it moves whole to the next page rather than splitting mid-rotation).
+ */
+export class RotatedElement extends PDFElement {
+    constructor({ angle, child }) {
+        super();
+        this.x = 0;
+        this.y = 0;
+        this.width = 0;
+        this.height = 0;
+        this.angle = angle;
+        this.child = child;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        // Delegate entirely to the child, then record its box (position + size) as our own - the
+        // rotation does not change what space we take, only how the child is painted.
+        const size = this.child.calculateLayout(constraints, offset, ctx);
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = size.width;
+        this.height = size.height;
+        return size;
+    }
+    getProps() {
+        return {
+            angle: this.angle,
+            child: this.child,
+            x: this.x,
+            y: this.y,
+            width: this.width,
+            height: this.height,
+        };
+    }
+}

package/dist/elements/layout/struct-group.d.ts

@@ -0,0 +1,28 @@
+import { PDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
+/**
+ * A layout-TRANSPARENT wrapper that assigns an accessibility structure role (Table / TR / TH / TD / …) to
+ * its single child. It delegates ALL layout and fragmentation to the child, so the visual result is byte-
+ * identical; only its renderer opens a structure element and nests the child's tags underneath.
+ *
+ * Split across pages, the fitted and remainder halves share this group's `structId`, so it stays ONE
+ * logical structure element (a table broken over pages is a single <Table>, exactly as Acrobat produces).
+ */
+export declare class StructGroup extends PDFElement implements Fragmentable {
+    private role;
+    private child;
+    constructor({ role, child }: {
+        role: string;
+        child: PDFElement;
+    });
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /** Only splittable when the wrapped child is - so a StructGroup(Row) is moved whole to the next page,
+     *  not clipped at the boundary (isFragmentable honours this veto). */
+    canFragment(): boolean;
+    fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+    getProps(): {
+        role: string;
+        child: PDFElement;
+    };
+}

package/dist/elements/layout/struct-group.js

@@ -0,0 +1,42 @@
+import { PDFElement } from "../pdf-element.js";
+import { isFragmentable } from "../../layout/fragmentation.js";
+/**
+ * A layout-TRANSPARENT wrapper that assigns an accessibility structure role (Table / TR / TH / TD / …) to
+ * its single child. It delegates ALL layout and fragmentation to the child, so the visual result is byte-
+ * identical; only its renderer opens a structure element and nests the child's tags underneath.
+ *
+ * Split across pages, the fitted and remainder halves share this group's `structId`, so it stays ONE
+ * logical structure element (a table broken over pages is a single <Table>, exactly as Acrobat produces).
+ */
+export class StructGroup extends PDFElement {
+    constructor({ role, child }) {
+        super();
+        this.role = role;
+        this.child = child;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        return this.child.calculateLayout(constraints, offset, ctx);
+    }
+    /** Only splittable when the wrapped child is - so a StructGroup(Row) is moved whole to the next page,
+     *  not clipped at the boundary (isFragmentable honours this veto). */
+    canFragment() {
+        return isFragmentable(this.child);
+    }
+    fragment(maxHeight, width, ctx) {
+        if (!isFragmentable(this.child))
+            return { fitted: null, remainder: this };
+        const { fitted, remainder } = this.child.fragment(maxHeight, width, ctx);
+        // Re-wrap each half with the SAME role + identity, so both pages point at one structure element.
+        return {
+            fitted: fitted
+                ? new StructGroup({ role: this.role, child: fitted }).adoptStructId(this)
+                : null,
+            remainder: remainder
+                ? new StructGroup({ role: this.role, child: remainder }).adoptStructId(this)
+                : null,
+        };
+    }
+    getProps() {
+        return { role: this.role, child: this.child };
+    }
+}

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

@@ -20,6 +20,14 @@ interface PDFPageParams extends WithChildren {
     /** Laid out at the BOTTOM of the content box, repeated on every physical page. */
     footer?: PDFElement;
 }
+/**
+ * The full page (media box) size in points, orientation applied. This is what a `PageBuilder` sees as
+ * `pageSize`; `resolvePageContentBox` below then subtracts the margins.
+ */
+export declare function resolvePageSize(config: PDFPageConfig): {
+    width: number;
+    height: number;
+};
 /**
  * The content box of a page (inside the margins, orientation applied) for a fully
  * resolved config. Single source of truth, shared by `PageElement` layout and the page

package/dist/elements/page-element.js

@@ -1,7 +1,18 @@
-import { pageFormats } from "../constants/page-sizes.js";
+import { pageFormats, PageSize } from "../constants/page-sizes.js";
 import { Orientation } from "../renderer/pdf-config.js";
 import { BoxConstraints } from "../layout/box-constraints.js";
 import { PDFElement } from "./pdf-element.js";
+/**
+ * The full page (media box) size in points, orientation applied. This is what a `PageBuilder` sees as
+ * `pageSize`; `resolvePageContentBox` below then subtracts the margins.
+ */
+export function resolvePageSize(config) {
+    // Defaults to A4 when the config is not fully resolved, matching what PageRenderer does for the MediaBox.
+    const [pageW, pageH] = config.customSize ?? pageFormats[config.pageSize ?? PageSize.A4];
+    return config.orientation === Orientation.landscape
+        ? { width: pageH, height: pageW }
+        : { width: pageW, height: pageH };
+}
 /**
  * The content box of a page (inside the margins, orientation applied) for a fully
  * resolved config. Single source of truth, shared by `PageElement` layout and the page
@@ -63,6 +74,7 @@ export class PageElement extends PDFElement {
             pageConfig: this.config,
             textStyle: ctx.textStyle,
             onOverflow: ctx.onOverflow,
+            pageInfo: ctx.pageInfo, // the render pass supplies it; absent during pagination
         };
         // Place the header/footer bands; the body gets the region left in between (the whole
         // content box when there is neither - byte-identical to a plain page).

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

@@ -23,9 +23,25 @@ export interface PositioningFrame {
         size: Size;
     }, ctx: LayoutContext) => void>;
 }
+/**
+ * What a `PageBuilder` learns about the page it landed on. `pageNumber` is 1-based and counts PHYSICAL
+ * pages across the whole document (a logical `Page` that overflows contributes several); `pageCount` is
+ * the document's final physical page total. `pageSize` is the media box in points, orientation applied.
+ */
+export interface PageInfo {
+    pageNumber: number;
+    pageCount: number;
+    pageSize: {
+        width: number;
+        height: number;
+    };
+}
 export interface LayoutContext {
     metrics: FontMetrics;
     pageConfig: PDFPageConfig;
+    /** The page a `PageBuilder` is being laid out on. Only the render pass knows the real numbers, so
+     *  during pagination this is absent and a `PageBuilder` builds against a provisional "1 of 1". */
+    pageInfo?: PageInfo;
     /** The nearest enclosing positioning frame, if any (set by a `relative` Box). */
     frame?: PositioningFrame;
     /** The cascaded text style descendants inherit (CSS/Flutter-style). Seeded at the document root
@@ -37,6 +53,10 @@ export interface LayoutContext {
     onOverflow?: OverflowPolicy;
 }
 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;
     abstract getProps(): unknown;
     /**
      * Lays the element out: `constraints` bound its size (flows DOWN), `offset` is the
@@ -45,6 +65,21 @@ export declare abstract class PDFElement {
      * happens once at the IR -> backend seam.
      */
     abstract calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /**
+     * 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
+     * `Box({ width: "50%" })` inside a Row, where the child otherwise gets an unbounded main axis and the
+     * fraction would have nothing to resolve against. Default: the element is not relatively sized.
+     */
+    relativeSizeFactor(_horizontal: boolean): number | undefined;
+    /**
+     * 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
+     * they keep their natural size; but a stack holding an `Expanded`/`Spacer` has no leftover space to
+     * distribute unless it is told how much main axis it may occupy. Such a stack answers `true` here and
+     * the parent hands it the line's bounded main extent instead of `Infinity`. Default: no.
+     */
+    needsBoundedMain(_horizontal: boolean): boolean;
 }
 export declare abstract class SizedPDFElement extends PDFElement {
     protected x: number;

package/dist/elements/pdf-element.js

@@ -1,4 +1,38 @@
+let _nextStructId = 0;
 export class PDFElement {
+    constructor() {
+        // Stable identity for accessible (PDF/UA) tagging: assigned once at construction and carried through
+        // 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++;
+    }
+    get structId() {
+        return this._structId;
+    }
+    /** Make this element share `from`'s tagging identity - used by fragmentation clones. Returns this. */
+    adoptStructId(from) {
+        this._structId = from._structId;
+        return this;
+    }
+    /**
+     * 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
+     * `Box({ width: "50%" })` inside a Row, where the child otherwise gets an unbounded main axis and the
+     * fraction would have nothing to resolve against. Default: the element is not relatively sized.
+     */
+    relativeSizeFactor(_horizontal) {
+        return undefined;
+    }
+    /**
+     * 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
+     * they keep their natural size; but a stack holding an `Expanded`/`Spacer` has no leftover space to
+     * distribute unless it is told how much main axis it may occupy. Such a stack answers `true` here and
+     * the parent hands it the line's bounded main extent instead of `Infinity`. Default: no.
+     */
+    needsBoundedMain(_horizontal) {
+        return false;
+    }
 }
 export class SizedPDFElement extends PDFElement {
     constructor(data) {

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

@@ -23,6 +23,11 @@ interface RectangleElementParams extends SizedElement, WithChildren {
     /** `"hidden"` crops children to the box (CSS `overflow: hidden`); `"visible"` (default) lets a
      *  `Positioned` child spill over the edge. */
     overflow?: "hidden" | "visible";
+    /** Width as a fraction (0..1) of the offered width, instead of a fixed `width` (CSS `50%`). Only
+     *  resolves in a bounded region; an explicit `width` wins over it. */
+    widthFactor?: number;
+    /** Height as a fraction (0..1) of the offered height; see `widthFactor`. */
+    heightFactor?: number;
 }
 export declare class RectangleElement extends SizedPDFElement implements Fragmentable {
     private children;
@@ -34,7 +39,7 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
     private relative;
     private overflow;
     private sizeMemory;
-    constructor({ children, color, backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, }: RectangleElementParams);
+    constructor({ children, color, backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, widthFactor, heightFactor, }: RectangleElementParams);
     /**
      * Splits the bordered box across pages (box-decoration-break: clone - every fragment
      * gets its own full border). The children stack is packed into the space left after
@@ -45,6 +50,11 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
      */
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
     private cloneWithChildren;
+    relativeSizeFactor(horizontal: boolean): number | undefined;
+    /** 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;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     getProps(): {
         x: number;

package/dist/elements/rectangle-element.js

@@ -1,9 +1,9 @@
 import { Color } from "../common/color.js";
-import { BoxConstraints } from "../layout/box-constraints.js";
+import { BoxConstraints, resolveExtent } from "../layout/box-constraints.js";
 import { packChildren } from "../layout/fragmentation.js";
 import { SizedPDFElement, } 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, }) {
+    constructor({ children = [], color = new Color(0, 0, 0), backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, widthFactor, heightFactor, }) {
         super({ x: 0, y: 0, width, height });
         this.children = [];
         this.children = children;
@@ -15,7 +15,7 @@ export class RectangleElement extends SizedPDFElement {
         this.sideBorders = sideBorders;
         this.relative = relative ?? false;
         this.overflow = overflow ?? "visible";
-        this.sizeMemory = { x: 0, y: 0, width, height };
+        this.sizeMemory = { x: 0, y: 0, width, height, widthFactor, heightFactor };
     }
     /**
      * Splits the bordered box across pages (box-decoration-break: clone - every fragment
@@ -26,7 +26,10 @@ export class RectangleElement extends SizedPDFElement {
      * box is sized by what it actually holds on each page.
      */
     fragment(maxHeight, width, ctx) {
-        const boxWidth = this.sizeMemory.width ?? width;
+        // A percentage width resolves against the region width the page driver hands us, so a
+        // paginating %-box keeps its fraction on every page.
+        const boxWidth = this.sizeMemory.width ??
+            (this.sizeMemory.widthFactor !== undefined ? width * this.sizeMemory.widthFactor : width);
         const innerWidth = Math.max(0, boxWidth - 2 * this.borderWidth);
         // Border-box: the content is inset by the border on top and bottom, so a fragment
         // holding `c` of content is `c + 2*border` tall. (Derived, not a fudge factor.)
@@ -47,6 +50,9 @@ export class RectangleElement extends SizedPDFElement {
             x: 0,
             y: 0,
             width: this.sizeMemory.width,
+            widthFactor: this.sizeMemory.widthFactor,
+            // A split box is sized by its per-page content (height passed in), so the height factor
+            // is intentionally dropped here - box-decoration-break, same as an explicit height.
             height,
             children,
             color: this.color,
@@ -58,25 +64,43 @@ export class RectangleElement extends SizedPDFElement {
             overflow: this.overflow,
         });
     }
+    relativeSizeFactor(horizontal) {
+        return horizontal ? this.sizeMemory.widthFactor : this.sizeMemory.heightFactor;
+    }
+    /** 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) {
+        const requested = horizontal
+            ? [this.sizeMemory.width, this.sizeMemory.widthFactor]
+            : [this.sizeMemory.height, this.sizeMemory.heightFactor];
+        if (requested.some((v) => v !== undefined))
+            return false;
+        return this.children.some((c) => c.needsBoundedMain(horizontal));
+    }
     calculateLayout(constraints, offset, ctx) {
+        // An explicit extent is a fixed point size or a fraction of the offered box (relative sizing);
+        // the fraction only resolves in a bounded region. `undefined` = fill / shrink-wrap below.
+        const explicitWidth = resolveExtent(this.sizeMemory.width, this.sizeMemory.widthFactor, constraints.maxWidth, constraints.hasBoundedWidth);
+        const explicitHeight = resolveExtent(this.sizeMemory.height, this.sizeMemory.heightFactor, constraints.maxHeight, constraints.hasBoundedHeight);
         // Width: an explicit size wins (clamped), else fill the offered box. (Without this a
         // fixed box would balloon to the parent's size.)
         this.width =
-            this.sizeMemory.width !== undefined
-                ? constraints.constrainWidth(this.sizeMemory.width)
+            explicitWidth !== undefined
+                ? constraints.constrainWidth(explicitWidth)
                 : constraints.hasBoundedWidth
                     ? constraints.maxWidth
                     : this.width;
         // Width shrink-wrap: no explicit width AND an unbounded region (e.g. a `Box` badge inside a
         // `Positioned`). Resolved after the children are measured, just below.
-        const shrinkWrapWidth = this.sizeMemory.width === undefined && !constraints.hasBoundedWidth;
+        const shrinkWrapWidth = explicitWidth === undefined && !constraints.hasBoundedWidth;
         // Height: explicit wins; otherwise FILL a bounded region (e.g. inside an Expanded) but
         // SHRINK-WRAP the content in an unbounded one (a note box in a stack). Shrink-wrap is
         // resolved after the children are measured, just below.
-        const shrinkWrapHeight = this.sizeMemory.height === undefined && !constraints.hasBoundedHeight;
+        const shrinkWrapHeight = explicitHeight === undefined && !constraints.hasBoundedHeight;
         this.height =
-            this.sizeMemory.height !== undefined
-                ? constraints.constrainHeight(this.sizeMemory.height)
+            explicitHeight !== undefined
+                ? constraints.constrainHeight(explicitHeight)
                 : constraints.hasBoundedHeight
                     ? constraints.maxHeight
                     : this.height;
@@ -89,16 +113,28 @@ export class RectangleElement extends SizedPDFElement {
             ? { origin: { x: 0, y: 0 }, size: { width: 0, height: 0 }, place: [] }
             : undefined;
         const childCtx = frame ? { ...ctx, frame } : ctx;
-        // Lay out children stacked inside the border (inset by the border width). Width is
-        // finalized here; height is left unbounded so each child sizes to its own content.
+        // Lay out children stacked inside the border (inset by the border width). Width is finalized here;
+        // height is left unbounded so each child sizes to its own content - EXCEPT for a child that cannot
+        // lay itself out without a bound (a stack holding an `Expanded`/`Spacer`). That one gets the height
+        // still free inside the box, so its flex child has real leftover space instead of an infinite one.
         const innerWidth = shrinkWrapWidth
             ? Infinity
             : Math.max(0, (this.width ?? 0) - 2 * this.borderWidth);
+        const innerHeight = shrinkWrapHeight
+            ? Infinity
+            : Math.max(0, (this.height ?? 0) - 2 * this.borderWidth);
         let contentWidth = 0;
         let contentHeight = 0;
         let yCursor = this.y + this.borderWidth;
         for (const child of this.children) {
-            const childSize = child.calculateLayout(BoxConstraints.loose(innerWidth, Infinity), { x: this.x + this.borderWidth, y: yCursor }, childCtx);
+            const consumed = yCursor - (this.y + this.borderWidth);
+            // Same rule the flex helper applies: a child gets a finite main extent when it cannot lay itself
+            // out without one - a stack holding an `Expanded`/`Spacer`, or a child sized as a percentage of us.
+            const needsBound = child.needsBoundedMain(false) || child.relativeSizeFactor(false) !== undefined;
+            const childHeight = needsBound
+                ? Math.max(0, innerHeight - consumed) // Infinity - consumed stays Infinity, as it should
+                : Infinity;
+            const childSize = child.calculateLayout(BoxConstraints.loose(innerWidth, childHeight), { x: this.x + this.borderWidth, y: yCursor }, childCtx);
             yCursor += childSize.height;
             contentHeight += childSize.height;
             contentWidth = Math.max(contentWidth, childSize.width);

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

@@ -8,6 +8,11 @@ interface RowElementParams extends WithChildren {
     main?: MainAlign;
     /** Vertical alignment of each child (cross axis); defaults to `stretch`. */
     cross?: CrossAlign;
+    /** Width/height as points (fixed) or a fraction (0..1) of the offered box (relative sizing). */
+    width?: number;
+    height?: number;
+    widthFactor?: number;
+    heightFactor?: number;
 }
 /**
  * Horizontal stack: the mirror of `ContainerElement` (Column). Children are laid out
@@ -26,7 +31,12 @@ export declare class RowElement extends SizedPDFElement {
     private gap;
     private main;
     private cross;
-    constructor({ children, gap, main, cross }: RowElementParams);
+    private requested;
+    constructor({ children, gap, main, cross, width, height, widthFactor, heightFactor, }: RowElementParams);
+    relativeSizeFactor(horizontal: boolean): number | undefined;
+    /** The mirror of `ContainerElement`: a Row's OWN flex child needs a bounded width, and the need of any
+     *  descendant propagates on both axes (see the Column for the reasoning). */
+    needsBoundedMain(horizontal: boolean): boolean;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     getProps(): {
         x: number;