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

package/dist/elements/forms/push-button-element.js

@@ -0,0 +1,49 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * A push button (AcroForm /Btn, Pushbutton flag). Holds no value - it fires an action. Draws nothing
+ * itself: it reserves its box and emits a `formfield` IR node whose caption is baked into an /AP at the
+ * seam, so the button looks identical in every viewer and in print.
+ */
+export class PushButtonElement extends SizedPDFElement {
+    constructor(p) {
+        super({ x: 0, y: 0, width: p.width, height: p.height });
+        const fontSize = p.fontSize ?? 12;
+        this.spec = {
+            kind: "pushbutton",
+            name: p.name,
+            label: p.label,
+            action: p.action,
+            tooltip: p.tooltip,
+            readOnly: p.readOnly,
+            required: p.required,
+            hidden: p.hidden,
+            print: p.print,
+        };
+        this.style = {
+            border: p.border ?? new Color(154, 164, 178),
+            background: p.background ?? new Color(238, 240, 245),
+            color: p.color ?? new Color(0, 0, 0),
+            fontSize,
+            borderWidth: p.borderWidth ?? 1,
+        };
+        this.requested = { width: p.width, height: p.height, fontSize };
+    }
+    calculateLayout(constraints, offset, _ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = this.requested.width ?? (constraints.hasBoundedWidth ? constraints.maxWidth : 120);
+        this.height = this.requested.height ?? this.requested.fontSize + 14;
+        return { width: this.width, height: this.height };
+    }
+    getProps() {
+        return {
+            x: this.x,
+            y: this.y,
+            width: this.width ?? 0,
+            height: this.height ?? 0,
+            spec: this.spec,
+            style: this.style,
+        };
+    }
+}

package/dist/elements/forms/radio-element.d.ts

@@ -0,0 +1,52 @@
+import { Color } from "../../common/color.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "../pdf-element.js";
+import type { FieldStyle, RadioSpec } from "../../forms/field.js";
+export interface RadioParams {
+    /** The shared group name - radios with the same `group` are one mutually-exclusive field. */
+    group: string;
+    /** This button's export value - unique within the group. */
+    value: string;
+    /** Whether this button starts selected (at most one per group should be). */
+    selected?: boolean;
+    /** Tooltip / accessible name. */
+    tooltip?: string;
+    /** Show but do not allow changing the group. */
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before submitting. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). */
+    print?: boolean;
+    /** Button diameter in points (default 14). */
+    size?: number;
+    /** Dot colour (default black). */
+    color?: Color;
+    /** Ring colour (default a mid grey). */
+    border?: Color;
+    /** Fill behind the ring. */
+    background?: Color;
+    /** Ring thickness (default 1). */
+    borderWidth?: number;
+}
+/**
+ * One radio button (AcroForm /Btn, Radio flag). A small round leaf; several sharing a `group` become one
+ * mutually-exclusive field (see `RadioGroup` for the ergonomic wrapper). Draws nothing itself - it emits a
+ * `formfield` IR node whose radio spec bakes the ring + dot /AP at the seam.
+ */
+export declare class RadioElement extends SizedPDFElement {
+    private spec;
+    private style;
+    private size;
+    constructor(p: RadioParams);
+    calculateLayout(_constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    getProps(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        spec: RadioSpec;
+        style: FieldStyle;
+    };
+}

package/dist/elements/forms/radio-element.js

@@ -0,0 +1,49 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * One radio button (AcroForm /Btn, Radio flag). A small round leaf; several sharing a `group` become one
+ * mutually-exclusive field (see `RadioGroup` for the ergonomic wrapper). Draws nothing itself - it emits a
+ * `formfield` IR node whose radio spec bakes the ring + dot /AP at the seam.
+ */
+export class RadioElement extends SizedPDFElement {
+    constructor(p) {
+        const size = p.size ?? 14;
+        super({ x: 0, y: 0, width: size, height: size });
+        this.size = size;
+        this.spec = {
+            kind: "radio",
+            group: p.group,
+            value: p.value,
+            selected: p.selected,
+            tooltip: p.tooltip,
+            readOnly: p.readOnly,
+            required: p.required,
+            hidden: p.hidden,
+            print: p.print,
+        };
+        this.style = {
+            border: p.border ?? new Color(102, 102, 102),
+            background: p.background,
+            color: p.color ?? new Color(0, 0, 0),
+            fontSize: 0,
+            borderWidth: p.borderWidth ?? 1,
+        };
+    }
+    calculateLayout(_constraints, offset, _ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = this.size;
+        this.height = this.size;
+        return { width: this.size, height: this.size };
+    }
+    getProps() {
+        return {
+            x: this.x,
+            y: this.y,
+            width: this.width ?? 0,
+            height: this.height ?? 0,
+            spec: this.spec,
+            style: this.style,
+        };
+    }
+}

package/dist/elements/forms/signature-element.d.ts

@@ -0,0 +1,54 @@
+import { Color } from "../../common/color.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "../pdf-element.js";
+import type { FieldStyle, SignatureSpec } from "../../forms/field.js";
+export interface SignatureFieldParams {
+    /** The field name (/T) - unique in the document. */
+    name: string;
+    /** A hint drawn inside the empty box, e.g. "Signature". */
+    label?: string;
+    /** Tooltip / accessible name. */
+    tooltip?: string;
+    /** Draw it but do not let it be signed. */
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before submitting. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). */
+    print?: boolean;
+    /** Box width in points; omit to fill the offered width. */
+    width?: number;
+    /** Box height in points (default 48 - room for a signature). */
+    height?: number;
+    /** Hint font size (default 9). */
+    fontSize?: number;
+    /** Hint colour (default a muted grey). */
+    color?: Color;
+    /** Box border + signing-rule colour (default a mid grey). */
+    border?: Color;
+    /** Box background fill. */
+    background?: Color;
+    /** Border thickness (default 1). */
+    borderWidth?: number;
+}
+/**
+ * A signature field (AcroForm /Sig) - a PLACEHOLDER someone can sign later. jasy creates the field and
+ * its empty "sign here" appearance; it does not sign (that needs a certificate and a byte-range digest -
+ * a separate feature). Draws nothing itself: it reserves its box and emits a `formfield` IR node.
+ */
+export declare class SignatureFieldElement extends SizedPDFElement {
+    private spec;
+    private style;
+    private requested;
+    constructor(p: SignatureFieldParams);
+    calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    getProps(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        spec: SignatureSpec;
+        style: FieldStyle;
+    };
+}

package/dist/elements/forms/signature-element.js

@@ -0,0 +1,47 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * A signature field (AcroForm /Sig) - a PLACEHOLDER someone can sign later. jasy creates the field and
+ * its empty "sign here" appearance; it does not sign (that needs a certificate and a byte-range digest -
+ * a separate feature). Draws nothing itself: it reserves its box and emits a `formfield` IR node.
+ */
+export class SignatureFieldElement extends SizedPDFElement {
+    constructor(p) {
+        super({ x: 0, y: 0, width: p.width, height: p.height });
+        this.spec = {
+            kind: "signature",
+            name: p.name,
+            label: p.label,
+            tooltip: p.tooltip,
+            readOnly: p.readOnly,
+            required: p.required,
+            hidden: p.hidden,
+            print: p.print,
+        };
+        this.style = {
+            border: p.border ?? new Color(154, 164, 178),
+            background: p.background,
+            color: p.color ?? new Color(107, 114, 128),
+            fontSize: p.fontSize ?? 9,
+            borderWidth: p.borderWidth ?? 1,
+        };
+        this.requested = { width: p.width, height: p.height };
+    }
+    calculateLayout(constraints, offset, _ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = this.requested.width ?? (constraints.hasBoundedWidth ? constraints.maxWidth : 240);
+        this.height = this.requested.height ?? 48;
+        return { width: this.width, height: this.height };
+    }
+    getProps() {
+        return {
+            x: this.x,
+            y: this.y,
+            width: this.width ?? 0,
+            height: this.height ?? 0,
+            spec: this.spec,
+            style: this.style,
+        };
+    }
+}

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

@@ -0,0 +1,61 @@
+import { Color } from "../../common/color.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "../pdf-element.js";
+import type { FieldAlign, FieldStyle, TextFieldSpec } from "../../forms/field.js";
+export interface TextFieldParams {
+    /** The field name (/T) - unique in the document; you read the value back by it. */
+    name: string;
+    /** Initial value (/V). */
+    value?: string;
+    /** Tooltip / accessible name (/TU). */
+    tooltip?: string;
+    /** Wrap across lines instead of one line. */
+    multiline?: boolean;
+    /** Mask the input. */
+    password?: boolean;
+    /** Maximum character count. */
+    maxLength?: number;
+    /** Show but do not allow editing. */
+    readOnly?: boolean;
+    /** How the value sits in the box (default left). */
+    align?: FieldAlign;
+    /** Mark it as a field that must be filled in before submitting. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). */
+    print?: boolean;
+    /** Box width in points; omit to fill the offered width. */
+    width?: number;
+    /** Box height in points; omit for a single-line default (`multiline` wants an explicit height). */
+    height?: number;
+    /** Value font size; `0` = viewer auto-size. */
+    fontSize?: number;
+    /** Value text colour. */
+    color?: Color;
+    /** Box border colour (omit for no border). */
+    border?: Color;
+    /** Box background fill (omit for transparent). */
+    background?: Color;
+    /** Border thickness in points. */
+    borderWidth?: number;
+}
+/**
+ * A text input field (AcroForm /Tx). A leaf that draws NOTHING itself: it reserves its box in the layout
+ * and emits a `formfield` IR node that becomes a Widget annotation + /AcroForm field at the seam.
+ */
+export declare class TextFieldElement extends SizedPDFElement {
+    private spec;
+    private style;
+    private requested;
+    constructor(p: TextFieldParams);
+    calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    getProps(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        spec: TextFieldSpec;
+        style: FieldStyle;
+    };
+}

package/dist/elements/forms/text-field-element.js

@@ -0,0 +1,54 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * A text input field (AcroForm /Tx). A leaf that draws NOTHING itself: it reserves its box in the layout
+ * and emits a `formfield` IR node that becomes a Widget annotation + /AcroForm field at the seam.
+ */
+export class TextFieldElement extends SizedPDFElement {
+    constructor(p) {
+        super({ x: 0, y: 0, width: p.width, height: p.height });
+        const fontSize = p.fontSize ?? 12;
+        this.spec = {
+            kind: "text",
+            name: p.name,
+            value: p.value,
+            tooltip: p.tooltip,
+            multiline: p.multiline,
+            password: p.password,
+            maxLength: p.maxLength,
+            readOnly: p.readOnly,
+            align: p.align,
+            required: p.required,
+            hidden: p.hidden,
+            print: p.print,
+        };
+        this.style = {
+            border: p.border,
+            background: p.background,
+            color: p.color ?? new Color(0, 0, 0),
+            fontSize,
+            borderWidth: p.borderWidth ?? 1,
+        };
+        this.requested = { width: p.width, height: p.height, fontSize };
+    }
+    calculateLayout(constraints, offset, _ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        // Width: explicit, else fill the offered box (a form field with no width spans the column).
+        this.width = this.requested.width ?? (constraints.hasBoundedWidth ? constraints.maxWidth : 200);
+        // Height: explicit, else a comfortable single line (font size + padding). Multiline without an
+        // explicit height still gets the single-line default - the caller should size a multiline box.
+        this.height = this.requested.height ?? this.requested.fontSize + 9;
+        return { width: this.width, height: this.height };
+    }
+    getProps() {
+        return {
+            x: this.x,
+            y: this.y,
+            width: this.width ?? 0,
+            height: this.height ?? 0,
+            spec: this.spec,
+            style: this.style,
+        };
+    }
+}

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

@@ -1,3 +1,4 @@
+import type { Radii } from "../ir/display-list.js";
 import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
 import { LayoutContext, SizedPDFElement } from "./pdf-element.js";
 export declare enum BoxFit {
@@ -55,9 +56,20 @@ interface ImageElementParams {
     widthFactor?: number;
     /** Height as a fraction (0..1) of the offered height; see `widthFactor`. */
     heightFactor?: number;
+    /** Lower / upper bounds per axis, in points or as a fraction; see `SizingParams`. */
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    minWidthFactor?: number;
+    maxWidthFactor?: number;
+    minHeightFactor?: number;
+    maxHeightFactor?: number;
+    /** width / height; overrides the image's OWN ratio (CSS `aspect-ratio`), `fit` then places it. */
+    aspectRatio?: number;
     fit?: BoxFit;
-    /** Corner radius in points; rounds the image box (0 = sharp, default). */
-    radius?: number;
+    /** Corner radius in points - one number or per corner; rounds the image box (0 = sharp, default). */
+    radius?: number | Radii;
     /** Alternate text for accessibility (tagged PDF). With `alt` the image is a Figure; without, decoration. */
     alt?: string;
 }
@@ -69,8 +81,10 @@ export declare class ImageElement extends SizedPDFElement {
     private radius;
     private readonly alt?;
     private requested;
+    /** min/max/aspectRatio, kept as given so every layout pass re-resolves them. */
+    private sizing;
     private intrinsic?;
-    constructor({ image, width, height, widthFactor, heightFactor, fit, radius, alt, }: ImageElementParams);
+    constructor({ image, width, height, widthFactor, heightFactor, fit, radius, alt, ...sizing }: ImageElementParams);
     /**
      * Loads the image and records its intrinsic pixel size. Runs in the async pre-layout pass (layout
      * itself is synchronous and cannot await jimp) so `calculateLayout` can turn a width-only image
@@ -87,7 +101,7 @@ export declare class ImageElement extends SizedPDFElement {
         height: number | undefined;
         image: CustomImage;
         fit: BoxFit;
-        radius: number;
+        radius: number | Radii;
         alt: string | undefined;
     };
 }

package/dist/elements/image-element.js

@@ -1,7 +1,7 @@
 import { getImageDimensions } from "../utils/image-helper.js";
 import { latin1FromBytes } from "../utils/bytes.js";
 import { readFileBytesAsync } from "../platform/node-fs.js";
-import { resolveExtent } from "../layout/box-constraints.js";
+import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
 import { SizedPDFElement } from "./pdf-element.js";
 // path.extname without node:path (browser-safe): the substring from the last dot, if it sits after the
 // last slash (so a dot in a directory name does not count). Enough for image file extensions.
@@ -100,7 +100,7 @@ export class CustomBytesImage extends CustomImage {
     }
 }
 export class ImageElement extends SizedPDFElement {
-    constructor({ image, width, height, widthFactor, heightFactor, fit = BoxFit.none, radius, alt, }) {
+    constructor({ image, width, height, widthFactor, heightFactor, fit = BoxFit.none, radius, alt, ...sizing }) {
         // Seed this.width/height from the request so getProps() reflects it before layout; calculateLayout
         // then reads `requested` (never the mutated fields) and overwrites these with the laid-out size.
         super({ x: 0, y: 0, width });
@@ -109,6 +109,7 @@ export class ImageElement extends SizedPDFElement {
         this.requested = { width, height };
         this.widthFactor = widthFactor;
         this.heightFactor = heightFactor;
+        this.sizing = sizing;
         this.fit = fit;
         this.radius = radius ?? 0;
         this.alt = alt;
@@ -136,22 +137,36 @@ export class ImageElement extends SizedPDFElement {
         this.y = offset.y;
         // Relative sizing: a fixed size or a fraction of the offered box (fraction only in a bounded axis).
         // Read from `requested` (not this.width/height, which we overwrite below) so every pass re-resolves.
-        let w = resolveExtent(this.requested.width, this.widthFactor, constraints.maxWidth, constraints.hasBoundedWidth);
-        let h = resolveExtent(this.requested.height, this.heightFactor, constraints.maxHeight, constraints.hasBoundedHeight);
-        // Aspect auto-size: when the user pinned exactly ONE axis, derive the other from the intrinsic
-        // ratio (CSS `width: 50%; height: auto`). Only fires once the pre-pass resolved the pixel size.
-        if (this.intrinsic && this.intrinsic.width > 0 && this.intrinsic.height > 0) {
+        const specs = extentSpecs({
+            ...this.sizing,
+            width: this.requested.width,
+            height: this.requested.height,
+            widthFactor: this.widthFactor,
+            heightFactor: this.heightFactor,
+        });
+        // An explicit `aspectRatio` wins over the image's own, as it does in CSS - and only it may size a
+        // box with NEITHER axis pinned. Left to the intrinsic ratio that would change what an unsized image
+        // has always done here (fill both axes and let `fit` sort it out).
+        const resolved = resolveSize(specs.width, specs.height, this.sizing.aspectRatio, constraints);
+        let w = resolved.width;
+        let h = resolved.height;
+        const bounds = resolved.constraints;
+        // Aspect auto-size: when exactly ONE axis is pinned, derive the other from the intrinsic ratio
+        // (CSS `width: 50%; height: auto`). Only fires once the pre-pass resolved the pixel size.
+        if (this.sizing.aspectRatio === undefined &&
+            this.intrinsic &&
+            this.intrinsic.width > 0 &&
+            this.intrinsic.height > 0) {
             const ratio = this.intrinsic.width / this.intrinsic.height;
             if (w !== undefined && h === undefined)
-                h = w / ratio;
+                h = bounds.constrainHeight(w / ratio);
             else if (h !== undefined && w === undefined)
-                w = h * ratio;
+                w = bounds.constrainWidth(h * ratio);
         }
         // Fall back to the prior behavior for an unpinned axis: a bounded axis fills, otherwise keep the
         // requested fixed size (or undefined). Read from `requested`, never the mutated this.width/height.
-        this.width = w ?? (constraints.hasBoundedWidth ? constraints.maxWidth : this.requested.width);
-        this.height =
-            h ?? (constraints.hasBoundedHeight ? constraints.maxHeight : this.requested.height);
+        this.width = w ?? (bounds.hasBoundedWidth ? bounds.maxWidth : this.requested.width);
+        this.height = h ?? (bounds.hasBoundedHeight ? bounds.maxHeight : this.requested.height);
         // Top-left coordinates; the fit logic (renderer) and the Y-flip (seam) run later.
         return { width: this.width ?? 0, height: this.height ?? 0 };
     }

package/dist/elements/index.d.ts

@@ -8,6 +8,12 @@ export * from "./layout/expanded-element.js";
 export * from "./layout/padding-element.js";
 export * from "./layout/page-break-element.js";
 export * from "./layout/keep-together-element.js";
+export * from "./forms/text-field-element.js";
+export * from "./forms/checkbox-element.js";
+export * from "./forms/radio-element.js";
+export * from "./forms/choice-element.js";
+export * from "./forms/push-button-element.js";
+export * from "./forms/signature-element.js";
 export * from "./layout/default-text-style-element.js";
 export * from "./layout/positioned-element.js";
 export * from "./layout/link-element.js";

package/dist/elements/index.js

@@ -8,6 +8,12 @@ export * from "./layout/expanded-element.js";
 export * from "./layout/padding-element.js";
 export * from "./layout/page-break-element.js";
 export * from "./layout/keep-together-element.js";
+export * from "./forms/text-field-element.js";
+export * from "./forms/checkbox-element.js";
+export * from "./forms/radio-element.js";
+export * from "./forms/choice-element.js";
+export * from "./forms/push-button-element.js";
+export * from "./forms/signature-element.js";
 export * from "./layout/default-text-style-element.js";
 export * from "./layout/positioned-element.js";
 export * from "./layout/link-element.js";

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

@@ -9,7 +9,7 @@ export declare class ExpandedElement extends FlexiblePDFElement implements Fragm
     private y;
     private width;
     private height;
-    constructor({ flex, child }: ExpandedElementParams);
+    constructor({ flex, basis, basisFactor, child }: ExpandedElementParams);
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     /**
      * When the column paginates, a flex region can't "fill" across pages, so it delegates to
@@ -24,6 +24,8 @@ export declare class ExpandedElement extends FlexiblePDFElement implements Fragm
         y: number;
         width: number;
         height: number;
+        basis: number;
+        basisFactor: number | undefined;
         child: PDFElement;
     };
 }

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

@@ -3,8 +3,8 @@ import { FlexiblePDFElement, } from "../pdf-element.js";
 import { BoxConstraints } from "../../layout/box-constraints.js";
 import { isFragmentable } from "../../layout/fragmentation.js";
 export class ExpandedElement extends FlexiblePDFElement {
-    constructor({ flex, child }) {
-        super({ flex });
+    constructor({ flex, basis, basisFactor, child }) {
+        super({ flex, basis, basisFactor });
         this.x = 0;
         this.y = 0;
         this.width = 0;
@@ -50,7 +50,14 @@ export class ExpandedElement extends FlexiblePDFElement {
         };
     }
     cloneWithChild(child) {
-        return new ExpandedElement({ flex: this.flex, child });
+        // The basis has to come along: a fragment that lost it would claim only its share of the leftover,
+        // so a `flexBasis` slot would silently change width on the page it continues onto.
+        return new ExpandedElement({
+            flex: this.flex,
+            basis: this.basis,
+            basisFactor: this.basisFactor,
+            child,
+        });
     }
     getProps() {
         return {
@@ -58,6 +65,8 @@ export class ExpandedElement extends FlexiblePDFElement {
             y: this.y,
             width: this.width,
             height: this.height,
+            basis: this.basis,
+            basisFactor: this.basisFactor,
             child: this.child,
         };
     }

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

@@ -1,8 +1,10 @@
 import { PDFElement, LayoutContext, WithChild, SizedPDFElement } from "../pdf-element.js";
 import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
 import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
+import { type EdgeSpecs } from "../../layout/insets.js";
 interface PaddingElementParams extends WithChild {
-    margin: [number, number, number, number];
+    /** Still unresolved: a side may be a percentage of the offered WIDTH (see `Insets`). */
+    margin: EdgeSpecs;
 }
 export declare class PaddingElement extends SizedPDFElement implements Fragmentable {
     private child;
@@ -25,7 +27,7 @@ export declare class PaddingElement extends SizedPDFElement implements Fragmenta
         y: number;
         width: number | undefined;
         height: number | undefined;
-        margin: [number, number, number, number];
+        margin: EdgeSpecs;
         child: PDFElement;
     };
 }

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

@@ -2,6 +2,7 @@ import { Validator } from "../../validators/element-validator.js";
 import { SizedPDFElement } from "../pdf-element.js";
 import { BoxConstraints } from "../../layout/box-constraints.js";
 import { isFragmentable } from "../../layout/fragmentation.js";
+import { resolveEdges } from "../../layout/insets.js";
 export class PaddingElement extends SizedPDFElement {
     constructor({ margin, child }) {
         super({ x: 0, y: 0 });
@@ -18,7 +19,7 @@ export class PaddingElement extends SizedPDFElement {
         if (!isFragmentable(this.child)) {
             return { fitted: null, remainder: this };
         }
-        const [marginTop, marginRight, marginBottom, marginLeft] = this.margin;
+        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, width);
         const childWidth = width - marginLeft - marginRight;
         const childMaxHeight = maxHeight - marginTop - marginBottom;
         const split = this.child.fragment(childMaxHeight, childWidth, ctx);
@@ -48,7 +49,8 @@ export class PaddingElement extends SizedPDFElement {
             this.width = constraints.maxWidth;
         this.x = offset.x;
         this.y = offset.y;
-        const [marginTop, marginRight, marginBottom, marginLeft] = this.margin;
+        // Percentages resolve against the width we were OFFERED, so every pass gets the same answer.
+        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, constraints.maxWidth);
         // The child is inset by the margins: shifted down/right, narrowed by the
         // horizontal margins, and left height-unbounded so it sizes to its own content.
         const childOffset = {

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

@@ -27,6 +27,8 @@ export class PageBuilderElement extends PDFElement {
         return (ctx.pageInfo ?? {
             pageNumber: 1,
             pageCount: 1,
+            subPageNumber: 1,
+            subPageTotalPages: 1,
             pageSize: resolvePageSize(ctx.pageConfig),
         });
     }