@jasy/pdf 1.0.0-alpha.5 → 1.0.0-alpha.7

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
@@ -25,6 +36,19 @@ export function resolvePageContentBox(config) {
  * no header/footer the bands are zero and the body equals the full content box - identical
  * to a page without them.
  */
+/**
+ * The page's positioning frame: its CONTENT box (paper minus margins). Header, footer and body all
+ * resolve a `Positioned` against this same box, so `top`/`bottom` mean the same thing in each.
+ *
+ * `layoutPageBands` lays the bands out, so its caller must hand it a context carrying this frame -
+ * otherwise a `Positioned` in a band has nothing to resolve against (ISSUE-4). A caller that only
+ * wants the band HEIGHTS may throw the frame away without draining it: an out-of-flow child
+ * contributes no height.
+ */
+export function pageFrame(config) {
+    const { origin, width, height } = resolvePageContentBox(config);
+    return { origin, size: { width, height }, place: [] };
+}
 export function layoutPageBands(config, header, footer, ctx) {
     const { origin, width, height } = resolvePageContentBox(config);
     let headerHeight = 0;
@@ -33,8 +57,13 @@ export function layoutPageBands(config, header, footer, ctx) {
     }
     let footerHeight = 0;
     if (footer) {
-        // Measure first to learn its height, then place it flush against the bottom edge.
-        footerHeight = footer.calculateLayout(BoxConstraints.loose(width, Infinity), origin, ctx).height;
+        // Measure first to learn its height, then place it flush against the bottom edge. The MEASURING
+        // pass gets a throwaway `place` list: an out-of-flow child registers a placement every time it is
+        // laid out, and this subtree is laid out twice. Only the second, real pass may register.
+        const measureCtx = ctx.frame
+            ? { ...ctx, frame: { ...ctx.frame, place: [] } }
+            : ctx;
+        footerHeight = footer.calculateLayout(BoxConstraints.loose(width, Infinity), origin, measureCtx).height;
         footer.calculateLayout(BoxConstraints.loose(width, Infinity), { x: origin.x, y: origin.y + height - footerHeight }, ctx);
     }
     return {
@@ -63,25 +92,33 @@ 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
         };
+        // The PAGE is a positioning frame, and the frame is the content box - not the body region left
+        // over between the bands. So `Positioned` means the same thing in the header, in the footer and
+        // in the body, `bottom: 0` is the foot of the page rather than the top of the footer, and adding
+        // a header no longer shifts a page-level `Positioned` that nobody touched. A `relative` Box
+        // still overrides it for its own subtree.
+        //
+        // Built BEFORE the bands are laid out: they need to see it, and their heights are not known yet
+        // anyway. (That is the whole of ISSUE-4 - a `Positioned` in a band had no frame to resolve
+        // against, so it silently stayed at the page's top-left corner.)
+        const frame = pageFrame(this.config);
+        const frameCtx = { ...pageCtx, frame };
         // 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).
-        const bands = layoutPageBands(this.config, this.header, this.footer, pageCtx);
+        const bands = layoutPageBands(this.config, this.header, this.footer, frameCtx);
         const childConstraints = BoxConstraints.loose(bands.bodyWidth, bands.bodyHeight);
-        // The page body is itself a positioning frame: a `Positioned` with no `relative` ancestor
-        // resolves against the content box (a `relative` Box overrides it for its own subtree). Drained
-        // after the body is laid out, so a page-level Positioned isn't a silent no-op.
-        const frame = {
-            origin: bands.bodyOrigin,
-            size: { width: bands.bodyWidth, height: bands.bodyHeight },
-            place: [],
-        };
-        const bodyCtx = { ...pageCtx, frame };
-        this.children.forEach((child) => child.calculateLayout(childConstraints, bands.bodyOrigin, bodyCtx));
+        this.children.forEach((child) => child.calculateLayout(childConstraints, bands.bodyOrigin, frameCtx));
+        // Drained last, once every band and the body have registered: an out-of-flow child is placed
+        // against the final frame box and paints on top of the flow content.
+        //
+        // The callback gets `frameCtx`, not `pageCtx`: a `Positioned` NESTED inside an out-of-flow child
+        // must still see a frame. It appends to `frame.place` while we walk it, and a `for..of` over an
+        // array visits what was appended, so nested placements drain in the same loop.
         for (const place of frame.place)
-            place(frame, pageCtx);
-        const { width, height } = resolvePageContentBox(this.config);
-        return { width, height };
+            place(frame, frameCtx);
+        return { width: frame.size.width, height: frame.size.height };
     }
     getProps() {
         return {

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
@@ -35,6 +51,10 @@ export interface LayoutContext {
     /** What to do when an element overflows a page region and cannot break (set from the render option;
      *  absent = clip silently). Evaluated in `packChildren` where the forced placement happens. */
     onOverflow?: OverflowPolicy;
+    /** The FULL body height of the current page (between header and footer), set by the page driver. A
+     *  `keepTogether` group reads it to decide the degrade rule: veto splitting only when the group would
+     *  fit on a fresh page; a group taller than a whole page drops the veto and splits. */
+    pageBodyHeight?: number;
 }
 export declare abstract class PDFElement {
     private _structId;
@@ -49,6 +69,45 @@ 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;
+    /**
+     * 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, 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.
+     * Default: no.
+     */
+    hasForcedBreak(): boolean;
+    /**
+     * Whether this element asks to START on a fresh page (CSS `break-before: page`, react-pdf's `break`
+     * prop). Read by the parent packer at the child boundary, not by the element itself; ignored when the
+     * element is already at the top of a region (nothing before it), so it never makes an empty page.
+     * Default: no.
+     */
+    breaksBefore(): boolean;
+    /**
+     * Whether everything AFTER this element must start a fresh page (CSS `break-after: page`). Read by the
+     * parent packer once this element has been placed whole. Default: no.
+     */
+    breaksAfter(): boolean;
 }
 export declare abstract class SizedPDFElement extends PDFElement {
     protected x: number;

package/dist/elements/pdf-element.js

@@ -14,6 +14,57 @@ export class PDFElement {
         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;
+    }
+    /**
+     * 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() {
+        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.
+     * Default: no.
+     */
+    hasForcedBreak() {
+        return false;
+    }
+    /**
+     * Whether this element asks to START on a fresh page (CSS `break-before: page`, react-pdf's `break`
+     * prop). Read by the parent packer at the child boundary, not by the element itself; ignored when the
+     * element is already at the top of a region (nothing before it), so it never makes an empty page.
+     * Default: no.
+     */
+    breaksBefore() {
+        return false;
+    }
+    /**
+     * Whether everything AFTER this element must start a fresh page (CSS `break-after: page`). Read by the
+     * parent packer once this element has been placed whole. Default: no.
+     */
+    breaksAfter() {
+        return false;
+    }
 }
 export class SizedPDFElement extends PDFElement {
     constructor(data) {

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

@@ -23,6 +23,15 @@ 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;
+    /** Start this box on a fresh page (CSS `break-before: page`). */
+    breakBefore?: boolean;
+    /** Start everything after this box on a fresh page (CSS `break-after: page`). */
+    breakAfter?: boolean;
 }
 export declare class RectangleElement extends SizedPDFElement implements Fragmentable {
     private children;
@@ -33,8 +42,12 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
     private sideBorders?;
     private relative;
     private overflow;
+    private breakBefore;
+    private breakAfter;
     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, breakBefore, breakAfter, }: RectangleElementParams);
+    breaksBefore(): boolean;
+    breaksAfter(): boolean;
     /**
      * 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
@@ -44,7 +57,13 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
      * box is sized by what it actually holds on each page.
      */
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+    hasForcedBreak(): boolean;
     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 { packChildren } from "../layout/fragmentation.js";
+import { BoxConstraints, resolveExtent } from "../layout/box-constraints.js";
+import { childrenForceBreak, 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, breakBefore, breakAfter, }) {
         super({ x: 0, y: 0, width, height });
         this.children = [];
         this.children = children;
@@ -15,7 +15,15 @@ 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.breakBefore = breakBefore ?? false;
+        this.breakAfter = breakAfter ?? false;
+        this.sizeMemory = { x: 0, y: 0, width, height, widthFactor, heightFactor };
+    }
+    breaksBefore() {
+        return this.breakBefore;
+    }
+    breaksAfter() {
+        return this.breakAfter;
     }
     /**
      * Splits the bordered box across pages (box-decoration-break: clone - every fragment
@@ -26,27 +34,45 @@ 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.)
         const innerMaxHeight = maxHeight - 2 * this.borderWidth;
-        const { fitted, remainder } = packChildren(this.children, innerMaxHeight, innerWidth, ctx);
-        if (remainder.length === 0)
+        const { fitted, remainder, forceBreak } = packChildren(this.children, innerMaxHeight, innerWidth, ctx);
+        // 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)
             return { fitted: this, remainder: null };
         const contentHeight = (kids) => kids.reduce((sum, child) => sum +
             child.calculateLayout(BoxConstraints.loose(innerWidth, Infinity), { x: 0, y: 0 }, ctx)
                 .height, 0);
         return {
             fitted: this.cloneWithChildren(fitted, contentHeight(fitted) + 2 * this.borderWidth),
-            remainder: this.cloneWithChildren(remainder, contentHeight(remainder) + 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.
+            remainder: remainder.length === 0
+                ? null
+                : this.cloneWithChildren(remainder, contentHeight(remainder) + 2 * this.borderWidth, this.breakAfter),
+            forceBreak,
         };
     }
-    cloneWithChildren(children, height) {
+    hasForcedBreak() {
+        return childrenForceBreak(this.children);
+    }
+    cloneWithChildren(children, height, breakAfter = false) {
         return new RectangleElement({
             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,
@@ -56,27 +82,46 @@ export class RectangleElement extends SizedPDFElement {
             sideBorders: this.sideBorders,
             relative: this.relative,
             overflow: this.overflow,
+            breakAfter,
         });
     }
+    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 +134,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,15 @@ 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;
+    /** Start this row on a fresh page (CSS `break-before: page`). */
+    breakBefore?: boolean;
+    /** Start everything after this row on a fresh page (CSS `break-after: page`). */
+    breakAfter?: boolean;
 }
 /**
  * Horizontal stack: the mirror of `ContainerElement` (Column). Children are laid out
@@ -26,7 +35,16 @@ export declare class RowElement extends SizedPDFElement {
     private gap;
     private main;
     private cross;
-    constructor({ children, gap, main, cross }: RowElementParams);
+    private breakBefore;
+    private breakAfter;
+    private requested;
+    constructor({ children, gap, main, cross, width, height, widthFactor, heightFactor, breakBefore, breakAfter, }: RowElementParams);
+    breaksBefore(): boolean;
+    breaksAfter(): boolean;
+    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;

package/dist/elements/row-element.js

@@ -1,5 +1,6 @@
+import { resolveExtent } from "../layout/box-constraints.js";
 import { FlexLayoutHelper, HORIZONTAL_AXIS } from "../utils/flex-layout.js";
-import { SizedPDFElement } from "./pdf-element.js";
+import { FlexiblePDFElement, SizedPDFElement, } from "./pdf-element.js";
 /**
  * Horizontal stack: the mirror of `ContainerElement` (Column). Children are laid out
  * left-to-right via the shared `FlexLayoutHelper` on the horizontal axis; fixed children
@@ -13,26 +14,62 @@ import { SizedPDFElement } from "./pdf-element.js";
  * Grid/Table concern.
  */
 export class RowElement extends SizedPDFElement {
-    constructor({ children, gap, main, cross }) {
+    constructor({ children, gap, main, cross, width, height, widthFactor, heightFactor, breakBefore, breakAfter, }) {
         super({ x: 0, y: 0 });
         this.children = children;
         this.gap = gap ?? 0;
         this.main = main ?? "start";
         this.cross = cross ?? "stretch";
+        this.requested = { width, height, widthFactor, heightFactor };
+        this.breakBefore = breakBefore ?? false;
+        this.breakAfter = breakAfter ?? false;
+    }
+    breaksBefore() {
+        return this.breakBefore;
+    }
+    breaksAfter() {
+        return this.breakAfter;
+    }
+    relativeSizeFactor(horizontal) {
+        return horizontal ? this.requested.widthFactor : this.requested.heightFactor;
+    }
+    /** 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) {
+        const requested = horizontal
+            ? [this.requested.width, this.requested.widthFactor]
+            : [this.requested.height, this.requested.heightFactor];
+        if (requested.some((v) => v !== undefined))
+            return false;
+        const ownFlexChild = horizontal && this.children.some((c) => c instanceof FlexiblePDFElement);
+        return ownFlexChild || this.children.some((c) => c.needsBoundedMain(horizontal));
     }
     calculateLayout(constraints, offset, ctx) {
         this.x = offset.x;
         this.y = offset.y;
-        // Width fills the offered space (flex children split the leftover); height is the
-        // tallest child unless the parent bounds it.
-        const mainAvail = constraints.hasBoundedWidth ? constraints.maxWidth : Infinity;
-        const crossAvail = constraints.hasBoundedHeight ? constraints.maxHeight : Infinity;
+        // Relative sizing: a pinned extent (fixed or a fraction of the offered box, clamped) wins; else
+        // width fills the offered space (flex children split the leftover) and height is the tallest child.
+        const explicitWidth = resolveExtent(this.requested.width, this.requested.widthFactor, constraints.maxWidth, constraints.hasBoundedWidth);
+        const explicitHeight = resolveExtent(this.requested.height, this.requested.heightFactor, constraints.maxHeight, constraints.hasBoundedHeight);
+        const boundedWidth = explicitWidth !== undefined
+            ? constraints.constrainWidth(explicitWidth)
+            : constraints.hasBoundedWidth
+                ? constraints.maxWidth
+                : undefined;
+        const boundedHeight = explicitHeight !== undefined
+            ? constraints.constrainHeight(explicitHeight)
+            : constraints.hasBoundedHeight
+                ? constraints.maxHeight
+                : undefined;
+        // Horizontal stack: main = width (children fill it), cross = height (children can stretch to it).
+        const mainAvail = boundedWidth ?? Infinity;
+        const crossAvail = boundedHeight ?? Infinity;
         let result = { mainUsed: 0, crossUsed: 0 };
         if (this.children.length > 0) {
             result = FlexLayoutHelper.layout(this.children, HORIZONTAL_AXIS, mainAvail, crossAvail, this.x, this.y, { gap: this.gap, main: this.main, cross: this.cross }, ctx);
         }
-        this.width = constraints.hasBoundedWidth ? constraints.maxWidth : result.mainUsed;
-        this.height = constraints.hasBoundedHeight ? constraints.maxHeight : result.crossUsed;
+        this.width = boundedWidth ?? result.mainUsed;
+        this.height = boundedHeight ?? result.crossUsed;
         return { width: this.width, height: this.height };
     }
     getProps() {

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

@@ -10,6 +10,15 @@ export interface TextSegment {
     fontColor?: Color;
     fontFamily?: string;
     fontSize?: number;
+    /** External URL: this segment becomes an inline hyperlink (a /Link annotation over its glyphs). */
+    href?: string;
+    /** Internal named destination (an `Anchor`): this segment links to it (a /GoTo /Link annotation). */
+    dest?: string;
+    /** Unset inherits the Text's own setting; `true`/`false` overrides it for this run only. */
+    underline?: boolean;
+    strikethrough?: boolean;
+    /** Extra space after every glyph, in points; unset inherits the Text's own value. */
+    letterSpacing?: number;
 }
 /** Accessibility role for the tagged structure tree: a heading level or a paragraph (the default). */
 export type TextRole = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p";
@@ -26,8 +35,17 @@ interface TextElementParams {
     maxLines?: number;
     /** What to do past `maxLines`: `"clip"` (default) drops them, `"ellipsis"` ends with "…". */
     overflow?: TextOverflow;
-    /** Line-height multiplier: each line is `fontSize * lineHeight` tall (default `1`). */
+    /** Line-height multiplier: each line is `fontSize * lineHeight` tall. Unset means the font's
+     *  natural line height (`ascent + descent + lineGap`), like CSS `line-height: normal`. */
     lineHeight?: number;
+    /** Draw a line under the text, at the position and thickness the font declares. */
+    underline?: boolean;
+    /** Draw a line through the text, at half its x-height. */
+    strikethrough?: boolean;
+    /** Let the underline step around descenders. Needs an embedded font. */
+    skipInk?: boolean;
+    /** Extra space after every glyph, in points (CSS `letter-spacing`). Default 0. */
+    letterSpacing?: number;
     /** Accessibility role for the tagged structure tree (heading level or paragraph; default `"p"`). */
     role?: TextRole;
 }
@@ -38,17 +56,25 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
     private readonly rawColor?;
     private readonly rawTextAlignment?;
     private readonly rawLineHeight?;
+    private readonly rawUnderline?;
+    private readonly rawStrikethrough?;
+    private readonly rawSkipInk?;
+    private readonly rawLetterSpacing?;
     private fontSize;
     private fontFamily;
     private fontStyle;
     private color;
     private textAlignment;
-    private lineHeight;
+    private lineHeight?;
+    private underline;
+    private strikethrough;
+    private skipInk;
+    private letterSpacing;
     private content;
     private maxLines?;
     private overflow;
     private readonly role?;
-    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, overflow, lineHeight, role, }: TextElementParams);
+    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, role, }: TextElementParams);
     private resolveStyle;
     private applyStyle;
     /**
@@ -84,7 +110,11 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
         textAlignment: HorizontalAlignment;
         maxLines: number | undefined;
         overflow: TextOverflow;
-        lineHeight: number;
+        lineHeight: number | undefined;
+        underline: boolean;
+        strikethrough: boolean;
+        skipInk: boolean;
+        letterSpacing: number;
         role: TextRole | undefined;
     };
 }