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

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/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),
         });
     }

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

@@ -3,6 +3,7 @@ import type { PDFPageConfig } from "./page-element.js";
 import type { ResolvedTextStyle } from "../text/text-style.js";
 import type { OverflowPolicy } from "../layout/fragmentation.js";
 import type { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
+import type { CrossAlign } from "../layout/alignment.js";
 /**
  * Everything the layout pass needs, threaded explicitly (no global singleton):
  * font metrics for measuring, and the geometry of the page currently being laid out.
@@ -29,8 +30,18 @@ export interface PositioningFrame {
  * the document's final physical page total. `pageSize` is the media box in points, orientation applied.
  */
 export interface PageInfo {
+    /** 1-based, counting PHYSICAL pages across the whole document. */
     pageNumber: number;
+    /** Physical pages in the whole document. */
     pageCount: number;
+    /**
+     * 1-based within the LOGICAL page this sheet came from - the `Page(...)` element the author wrote.
+     * A document of one `Page` has `subPageNumber === pageNumber`; a document of several (an invoice
+     * plus its attachment, say) restarts the count at each one.
+     */
+    subPageNumber: number;
+    /** Physical pages this logical page produced. */
+    subPageTotalPages: number;
     pageSize: {
         width: number;
         height: number;
@@ -108,6 +119,31 @@ export declare abstract class PDFElement {
      * parent packer once this element has been placed whole. Default: no.
      */
     breaksAfter(): boolean;
+    /**
+     * This child's own cross-axis alignment inside its Column / Row (CSS `align-self`), overriding the
+     * container's `align`. Lives on the base element because any child of a stack may set it, not just
+     * the sized ones. `undefined` means "follow the container".
+     */
+    alignSelf?: CrossAlign;
+    /** Sets `alignSelf` and returns the element, so a factory can thread it through in one expression. */
+    withAlignSelf(align: CrossAlign | undefined): this;
+    /**
+     * Where this child sits among its siblings (CSS `order`), lowest first, source order deciding ties.
+     * It moves the child in the LAYOUT only - the element tree, and therefore the reading order a tagged
+     * PDF exposes, is untouched. Default 0.
+     */
+    order: number;
+    /**
+     * How willingly this child gives up main-axis space when the line overflows (CSS `flex-shrink`),
+     * weighted by its own size as CSS does. **Default 0, deliberately unlike CSS's 1**: shrinking is a
+     * change of what a document LOOKS like, and every document written before this existed must keep
+     * laying out exactly as it did. Opt in per child.
+     */
+    flexShrink: number;
+    /** Sets `flexShrink` and returns the element. */
+    withFlexShrink(shrink: number | undefined): this;
+    /** Sets `order` and returns the element, so a factory can thread it through in one expression. */
+    withOrder(order: number | undefined): this;
 }
 export declare abstract class SizedPDFElement extends PDFElement {
     protected x: number;
@@ -120,14 +156,32 @@ export declare abstract class SizedPDFElement extends PDFElement {
 export declare abstract class FlexiblePDFElement extends PDFElement {
     protected flex: number;
     protected verticalChildAlignment: VerticalAlignment;
+    /** Points reserved before any leftover is shared out (CSS `flex-basis`); default 0. */
+    protected basis: number;
+    /** The same as a fraction of the line, for `flexBasis: "25%"`. */
+    protected basisFactor?: number;
     constructor(data: FlexibleElement);
     getFlex(): number;
+    /**
+     * The main extent this child starts from, before the leftover is shared out. `lineMain` is what the
+     * line offers its items (its extent minus the gaps), so a percentage basis resolves against the same
+     * base a percentage WIDTH already does - and falls back to 0 on an unbounded axis, where a fraction
+     * has no meaning.
+     */
+    /** Whether a PERCENTAGE basis was given - it resolves to 0 on an unbounded axis, so asking for the
+     *  number alone cannot tell "no basis" from "a basis that does not apply here". */
+    hasBasisFactor(): boolean;
+    getBasis(lineMain: number): number;
 }
 export declare enum HorizontalAlignment {
+    /** CSS `text-align: start` - the side the writing STARTS on: left in `ltr`, right in `rtl`. The
+     *  default, so a right-to-left paragraph begins on the right without anyone asking for it. */
+    start = "START",
     left = "LEFT",
     right = "RIGHT",
     center = "CENTER",
-    block = "BLOCK"
+    /** CSS `text-align: justify` - both edges line up, the last line of a paragraph excepted. */
+    justify = "JUSTIFY"
 }
 export declare enum VerticalAlignment {
     top = "TOP",
@@ -142,6 +196,10 @@ export interface WithChild {
 }
 export interface FlexibleElement {
     flex: number;
+    /** Points reserved before the leftover is shared out (CSS `flex-basis`). */
+    basis?: number;
+    /** The same as a fraction of the line, for `flexBasis: "25%"`. */
+    basisFactor?: number;
     verticalChildAlignment?: VerticalAlignment;
 }
 export interface SizedElement {

package/dist/elements/pdf-element.js

@@ -5,6 +5,19 @@ export class PDFElement {
         // 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++;
+        /**
+         * Where this child sits among its siblings (CSS `order`), lowest first, source order deciding ties.
+         * It moves the child in the LAYOUT only - the element tree, and therefore the reading order a tagged
+         * PDF exposes, is untouched. Default 0.
+         */
+        this.order = 0;
+        /**
+         * How willingly this child gives up main-axis space when the line overflows (CSS `flex-shrink`),
+         * weighted by its own size as CSS does. **Default 0, deliberately unlike CSS's 1**: shrinking is a
+         * change of what a document LOOKS like, and every document written before this existed must keep
+         * laying out exactly as it did. Opt in per child.
+         */
+        this.flexShrink = 0;
     }
     get structId() {
         return this._structId;
@@ -65,6 +78,31 @@ export class PDFElement {
     breaksAfter() {
         return false;
     }
+    /** Sets `alignSelf` and returns the element, so a factory can thread it through in one expression. */
+    withAlignSelf(align) {
+        if (align !== undefined)
+            this.alignSelf = align;
+        return this;
+    }
+    /** Sets `flexShrink` and returns the element. */
+    withFlexShrink(shrink) {
+        if (shrink !== undefined) {
+            if (!Number.isFinite(shrink) || shrink < 0) {
+                throw new Error(`Invalid flexShrink ${shrink}: it must be a number of at least 0.`);
+            }
+            this.flexShrink = shrink;
+        }
+        return this;
+    }
+    /** Sets `order` and returns the element, so a factory can thread it through in one expression. */
+    withOrder(order) {
+        if (order !== undefined) {
+            if (!Number.isFinite(order))
+                throw new Error(`Invalid order ${order}: it must be a number.`);
+            this.order = order;
+        }
+        return this;
+    }
 }
 export class SizedPDFElement extends PDFElement {
     constructor(data) {
@@ -83,17 +121,40 @@ export class FlexiblePDFElement extends PDFElement {
         super();
         this.flex = data.flex;
         this.verticalChildAlignment = data.verticalChildAlignment || VerticalAlignment.middle;
+        this.basis = data.basis ?? 0;
+        this.basisFactor = data.basisFactor;
     }
     getFlex() {
         return this.flex;
     }
+    /**
+     * The main extent this child starts from, before the leftover is shared out. `lineMain` is what the
+     * line offers its items (its extent minus the gaps), so a percentage basis resolves against the same
+     * base a percentage WIDTH already does - and falls back to 0 on an unbounded axis, where a fraction
+     * has no meaning.
+     */
+    /** Whether a PERCENTAGE basis was given - it resolves to 0 on an unbounded axis, so asking for the
+     *  number alone cannot tell "no basis" from "a basis that does not apply here". */
+    hasBasisFactor() {
+        return this.basisFactor !== undefined;
+    }
+    getBasis(lineMain) {
+        if (this.basisFactor !== undefined) {
+            return Number.isFinite(lineMain) ? lineMain * this.basisFactor : 0;
+        }
+        return this.basis;
+    }
 }
 export var HorizontalAlignment;
 (function (HorizontalAlignment) {
+    /** CSS `text-align: start` - the side the writing STARTS on: left in `ltr`, right in `rtl`. The
+     *  default, so a right-to-left paragraph begins on the right without anyone asking for it. */
+    HorizontalAlignment["start"] = "START";
     HorizontalAlignment["left"] = "LEFT";
     HorizontalAlignment["right"] = "RIGHT";
     HorizontalAlignment["center"] = "CENTER";
-    HorizontalAlignment["block"] = "BLOCK";
+    /** CSS `text-align: justify` - both edges line up, the last line of a paragraph excepted. */
+    HorizontalAlignment["justify"] = "JUSTIFY";
 })(HorizontalAlignment || (HorizontalAlignment = {}));
 export var VerticalAlignment;
 (function (VerticalAlignment) {

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

@@ -1,3 +1,5 @@
+import type { Radii } from "../ir/display-list.js";
+import type { GradientInput } from "../api/gradient.js";
 import { Color } from "../common/color.js";
 import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
 import { Fragmentable, FragmentResult } from "../layout/fragmentation.js";
@@ -12,10 +14,11 @@ export interface SideBorders {
 }
 interface RectangleElementParams extends SizedElement, WithChildren {
     color?: Color;
-    backgroundColor?: Color;
+    /** Solid colour, or a box-relative gradient the renderer resolves against this box. */
+    backgroundColor?: Color | GradientInput;
     borderWidth?: number;
-    /** Corner radius in points; 0 = sharp corners (default). */
-    radius?: number;
+    /** Corner radius in points - one number for all four corners, or per corner. 0 = sharp (default). */
+    radius?: number | Radii;
     /** Individual side borders; overrides the uniform `color` border when present. */
     sideBorders?: SideBorders;
     /** When true, this box is a positioning frame for `Positioned` descendants (CSS `relative`). */
@@ -28,6 +31,17 @@ interface RectangleElementParams extends SizedElement, WithChildren {
     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; derives whichever axis is left open (CSS `aspect-ratio`). */
+    aspectRatio?: 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`). */
@@ -45,7 +59,7 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
     private breakBefore;
     private breakAfter;
     private sizeMemory;
-    constructor({ children, color, backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, widthFactor, heightFactor, breakBefore, breakAfter, }: RectangleElementParams);
+    constructor({ children, color, backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, breakBefore, breakAfter, ...sizing }: RectangleElementParams);
     breaksBefore(): boolean;
     breaksAfter(): boolean;
     /**
@@ -72,9 +86,9 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
         height: number | undefined;
         children: PDFElement[];
         color: Color;
-        backgroundColor: Color | undefined;
+        backgroundColor: Color | GradientInput | undefined;
         borderWidth: number;
-        radius: number;
+        radius: number | Radii;
         sideBorders: SideBorders | undefined;
         overflow: "hidden" | "visible";
     };

package/dist/elements/rectangle-element.js

@@ -1,9 +1,9 @@
 import { Color } from "../common/color.js";
-import { BoxConstraints, resolveExtent } from "../layout/box-constraints.js";
+import { BoxConstraints, extentSpecs, resolveSize, } 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, widthFactor, heightFactor, breakBefore, breakAfter, }) {
+    constructor({ children = [], color = new Color(0, 0, 0), backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, breakBefore, breakAfter, ...sizing }) {
         super({ x: 0, y: 0, width, height });
         this.children = [];
         this.children = children;
@@ -17,7 +17,7 @@ export class RectangleElement extends SizedPDFElement {
         this.overflow = overflow ?? "visible";
         this.breakBefore = breakBefore ?? false;
         this.breakAfter = breakAfter ?? false;
-        this.sizeMemory = { x: 0, y: 0, width, height, widthFactor, heightFactor };
+        this.sizeMemory = { ...sizing, x: 0, y: 0, width, height };
     }
     breaksBefore() {
         return this.breakBefore;
@@ -102,15 +102,21 @@ export class RectangleElement extends SizedPDFElement {
     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);
+        const specs = extentSpecs(this.sizeMemory);
+        const resolved = resolveSize(specs.width, specs.height, this.sizeMemory.aspectRatio, constraints);
+        const explicitWidth = resolved.width;
+        const explicitHeight = resolved.height;
+        // min/max come back as narrowed constraints, so the fill and shrink-wrap paths below obey them too.
+        const bounds = resolved.constraints;
         // Width: an explicit size wins (clamped), else fill the offered box. (Without this a
         // fixed box would balloon to the parent's size.)
+        // Whether there is a region to fill is decided by the constraints we were GIVEN: a `maxWidth` caps
+        // a box, it does not turn a shrink-wrapping one into a filling one (CSS `max-width` does not either).
         this.width =
             explicitWidth !== undefined
-                ? constraints.constrainWidth(explicitWidth)
+                ? bounds.constrainWidth(explicitWidth)
                 : constraints.hasBoundedWidth
-                    ? constraints.maxWidth
+                    ? bounds.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.
@@ -121,9 +127,9 @@ export class RectangleElement extends SizedPDFElement {
         const shrinkWrapHeight = explicitHeight === undefined && !constraints.hasBoundedHeight;
         this.height =
             explicitHeight !== undefined
-                ? constraints.constrainHeight(explicitHeight)
+                ? bounds.constrainHeight(explicitHeight)
                 : constraints.hasBoundedHeight
-                    ? constraints.maxHeight
+                    ? bounds.maxHeight
                     : this.height;
         this.x = this.sizeMemory.x + offset.x;
         this.y = this.sizeMemory.y + offset.y;
@@ -161,11 +167,18 @@ export class RectangleElement extends SizedPDFElement {
             contentWidth = Math.max(contentWidth, childSize.width);
         }
         // No explicit width and no bounded region: shrink-wrap to the widest child.
+        // Clamped, so a min/max still applies to a box that sized itself to its content.
         if (shrinkWrapWidth)
-            this.width = contentWidth + 2 * this.borderWidth;
+            this.width = bounds.constrainWidth(contentWidth + 2 * this.borderWidth);
+        // A ratio on a shrink-wrapping box can only be applied HERE: before the children were measured
+        // there was no width to derive the height from.
+        const ratio = this.sizeMemory.aspectRatio;
+        const ratioSizesHeight = ratio !== undefined && ratio > 0 && shrinkWrapWidth && shrinkWrapHeight;
         // No explicit height and no bounded region: the border hugs its content.
-        if (shrinkWrapHeight)
-            this.height = contentHeight + 2 * this.borderWidth;
+        if (ratioSizesHeight)
+            this.height = bounds.constrainHeight((this.width ?? 0) / ratio);
+        else if (shrinkWrapHeight)
+            this.height = bounds.constrainHeight(contentHeight + 2 * this.borderWidth);
         // The box is sized now: place any out-of-flow `Positioned` descendants against its box.
         if (frame) {
             frame.origin = { x: this.x, y: this.y };

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

@@ -8,11 +8,28 @@ interface RowElementParams extends WithChildren {
     main?: MainAlign;
     /** Vertical alignment of each child (cross axis); defaults to `stretch`. */
     cross?: CrossAlign;
+    /** Lay the children out backwards along the main axis (CSS `row-reverse`). */
+    reverse?: boolean;
+    /** Let the children flow onto further lines when they do not fit (CSS `flex-wrap`). */
+    wrap?: boolean;
+    /** How the block of wrapped lines sits across the axis (CSS `align-content`). */
+    alignContent?: MainAlign;
     /** Width/height as points (fixed) or a fraction (0..1) of the offered box (relative sizing). */
     width?: number;
     height?: number;
     widthFactor?: number;
     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; derives whichever axis is left open (CSS `aspect-ratio`). */
+    aspectRatio?: 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`). */
@@ -35,10 +52,13 @@ export declare class RowElement extends SizedPDFElement {
     private gap;
     private main;
     private cross;
+    private reverse;
+    private wrap;
+    private alignContent?;
     private breakBefore;
     private breakAfter;
     private requested;
-    constructor({ children, gap, main, cross, width, height, widthFactor, heightFactor, breakBefore, breakAfter, }: RowElementParams);
+    constructor({ children, gap, main, cross, reverse, wrap, alignContent, width, height, breakBefore, breakAfter, ...sizing }: RowElementParams);
     breaksBefore(): boolean;
     breaksAfter(): boolean;
     relativeSizeFactor(horizontal: boolean): number | undefined;
@@ -55,6 +75,9 @@ export declare class RowElement extends SizedPDFElement {
         gap: number;
         main: MainAlign;
         cross: CrossAlign;
+        reverse: boolean;
+        wrap: boolean;
+        alignContent: MainAlign | undefined;
     };
 }
 export {};

package/dist/elements/row-element.js

@@ -1,4 +1,4 @@
-import { resolveExtent } from "../layout/box-constraints.js";
+import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
 import { FlexLayoutHelper, HORIZONTAL_AXIS } from "../utils/flex-layout.js";
 import { FlexiblePDFElement, SizedPDFElement, } from "./pdf-element.js";
 /**
@@ -14,13 +14,16 @@ import { FlexiblePDFElement, SizedPDFElement, } from "./pdf-element.js";
  * Grid/Table concern.
  */
 export class RowElement extends SizedPDFElement {
-    constructor({ children, gap, main, cross, width, height, widthFactor, heightFactor, breakBefore, breakAfter, }) {
+    constructor({ children, gap, main, cross, reverse, wrap, alignContent, width, height, breakBefore, breakAfter, ...sizing }) {
         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.reverse = reverse ?? false;
+        this.wrap = wrap ?? false;
+        this.alignContent = alignContent;
+        this.requested = { ...sizing, width, height };
         this.breakBefore = breakBefore ?? false;
         this.breakAfter = breakAfter ?? false;
     }
@@ -49,24 +52,33 @@ export class RowElement extends SizedPDFElement {
         this.y = offset.y;
         // 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 specs = extentSpecs(this.requested);
+        const resolved = resolveSize(specs.width, specs.height, this.requested.aspectRatio, constraints);
+        const { width: explicitWidth, height: explicitHeight, constraints: bounds } = resolved;
+        // Fill-or-shrink-wrap is decided by the constraints we were GIVEN; a min/max only caps the result.
         const boundedWidth = explicitWidth !== undefined
-            ? constraints.constrainWidth(explicitWidth)
+            ? bounds.constrainWidth(explicitWidth)
             : constraints.hasBoundedWidth
-                ? constraints.maxWidth
+                ? bounds.maxWidth
                 : undefined;
         const boundedHeight = explicitHeight !== undefined
-            ? constraints.constrainHeight(explicitHeight)
+            ? bounds.constrainHeight(explicitHeight)
             : constraints.hasBoundedHeight
-                ? constraints.maxHeight
+                ? bounds.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);
+            result = FlexLayoutHelper.layout(this.children, HORIZONTAL_AXIS, mainAvail, crossAvail, this.x, this.y, {
+                gap: this.gap,
+                main: this.main,
+                cross: this.cross,
+                reverse: this.reverse,
+                wrap: this.wrap,
+                alignContent: this.alignContent,
+            }, ctx);
         }
         this.width = boundedWidth ?? result.mainUsed;
         this.height = boundedHeight ?? result.crossUsed;
@@ -82,6 +94,9 @@ export class RowElement extends SizedPDFElement {
             gap: this.gap,
             main: this.main,
             cross: this.cross,
+            reverse: this.reverse,
+            wrap: this.wrap,
+            alignContent: this.alignContent,
         };
     }
 }