@jasy/pdf 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/elements/page-element.js

@@ -1,22 +1,29 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PageElement = void 0;
-exports.resolvePageContentBox = resolvePageContentBox;
-exports.layoutPageBands = layoutPageBands;
-const page_sizes_1 = require("../constants/page-sizes");
-const pdf_config_1 = require("../renderer/pdf-config");
-const box_constraints_1 = require("../layout/box-constraints");
-const pdf_element_1 = require("./pdf-element");
+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
  * driver so they can never drift.
  */
-function resolvePageContentBox(config) {
+export function resolvePageContentBox(config) {
     const margin = config.margin;
-    let width = page_sizes_1.pageFormats[config.pageSize][0] - margin.left - margin.right;
-    let height = page_sizes_1.pageFormats[config.pageSize][1] - margin.top - margin.bottom;
-    if (config.orientation === pdf_config_1.Orientation.landscape) {
+    const [pageW, pageH] = config.customSize ?? pageFormats[config.pageSize];
+    let width = pageW - margin.left - margin.right;
+    let height = pageH - margin.top - margin.bottom;
+    if (config.orientation === Orientation.landscape) {
         [width, height] = [height, width];
     }
     return { origin: { x: margin.left, y: margin.top }, width, height };
@@ -29,17 +36,35 @@ function resolvePageContentBox(config) {
  * no header/footer the bands are zero and the body equals the full content box - identical
  * to a page without them.
  */
-function layoutPageBands(config, header, footer, ctx) {
+/**
+ * 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;
     if (header) {
-        headerHeight = header.calculateLayout(box_constraints_1.BoxConstraints.loose(width, Infinity), origin, ctx).height;
+        headerHeight = header.calculateLayout(BoxConstraints.loose(width, Infinity), origin, ctx).height;
     }
     let footerHeight = 0;
     if (footer) {
-        // Measure first to learn its height, then place it flush against the bottom edge.
-        footerHeight = footer.calculateLayout(box_constraints_1.BoxConstraints.loose(width, Infinity), origin, ctx).height;
-        footer.calculateLayout(box_constraints_1.BoxConstraints.loose(width, Infinity), { x: origin.x, y: origin.y + height - footerHeight }, ctx);
+        // 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 {
         bodyOrigin: { x: origin.x, y: origin.y + headerHeight },
@@ -49,11 +74,11 @@ function layoutPageBands(config, header, footer, ctx) {
         footerHeight,
     };
 }
-class PageElement extends pdf_element_1.PDFElement {
+export class PageElement extends PDFElement {
     constructor({ children, config, header, footer }) {
         super();
         this.children = children;
-        this.config = config !== null && config !== void 0 ? config : {};
+        this.config = config ?? {};
         this.header = header;
         this.footer = footer;
     }
@@ -61,18 +86,39 @@ class PageElement extends pdf_element_1.PDFElement {
         // Merge the document defaults (carried in the context) with this page's overrides,
         // then hand descendants a context bound to THIS page's geometry. This is what
         // fixes the old last-page-wins global page-config bug.
-        this.config = Object.assign(Object.assign({}, ctx.pageConfig), this.config);
+        this.config = { ...ctx.pageConfig, ...this.config };
         const pageCtx = {
             metrics: ctx.metrics,
             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 childConstraints = box_constraints_1.BoxConstraints.loose(bands.bodyWidth, bands.bodyHeight);
-        this.children.forEach((child) => child.calculateLayout(childConstraints, bands.bodyOrigin, pageCtx));
-        const { width, height } = resolvePageContentBox(this.config);
-        return { width, height };
+        const bands = layoutPageBands(this.config, this.header, this.footer, frameCtx);
+        const childConstraints = BoxConstraints.loose(bands.bodyWidth, bands.bodyHeight);
+        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, frameCtx);
+        return { width: frame.size.width, height: frame.size.height };
     }
     getProps() {
         return {
@@ -87,4 +133,3 @@ class PageElement extends pdf_element_1.PDFElement {
         return this;
     }
 }
-exports.PageElement = PageElement;

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

@@ -1,12 +1,18 @@
-import { PageElement } from "./page-element";
-import { BoxConstraints, Offset, Size } from "../layout/box-constraints";
-import { LayoutContext, PDFElement, WithChildren } from "./pdf-element";
+import { PageElement } from "./page-element.js";
+import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
+import { LayoutContext, PDFElement, WithChildren } from "./pdf-element.js";
+import type { ResolvedTextStyle } from "../text/text-style.js";
 interface PDFDocumentParams extends WithChildren {
     children: PageElement[];
+    /** Document-level text defaults descendants inherit (seeded into the layout-context root). */
+    defaultTextStyle?: Partial<ResolvedTextStyle>;
 }
 export declare class PDFDocumentElement extends PDFElement {
     private children;
-    constructor({ children }: PDFDocumentParams);
+    private defaultTextStyle?;
+    constructor({ children, defaultTextStyle }: PDFDocumentParams);
+    /** The document-level text defaults; the renderer merges them into the cascade root. */
+    getDefaultTextStyle(): Partial<ResolvedTextStyle> | undefined;
     calculateLayout(_constraints: BoxConstraints, _offset: Offset, ctx: LayoutContext): Size;
     getProps(): PDFDocumentParams;
 }

package/dist/elements/pdf-document-element.js

@@ -1,22 +1,23 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PDFDocumentElement = void 0;
-const box_constraints_1 = require("../layout/box-constraints");
-const pdf_element_1 = require("./pdf-element");
-class PDFDocumentElement extends pdf_element_1.PDFElement {
-    constructor({ children }) {
+import { BoxConstraints } from "../layout/box-constraints.js";
+import { PDFElement } from "./pdf-element.js";
+export class PDFDocumentElement extends PDFElement {
+    constructor({ children, defaultTextStyle }) {
         super();
         this.children = children;
+        this.defaultTextStyle = defaultTextStyle;
+    }
+    /** The document-level text defaults; the renderer merges them into the cascade root. */
+    getDefaultTextStyle() {
+        return this.defaultTextStyle;
     }
     calculateLayout(_constraints, _offset, ctx) {
         // The document is the root: each page derives its own geometry, so it ignores the
         // incoming constraints/offset. It has no size of its own.
         const origin = { x: 0, y: 0 };
-        this.children.forEach((child) => child.calculateLayout(new box_constraints_1.BoxConstraints(), origin, ctx));
+        this.children.forEach((child) => child.calculateLayout(new BoxConstraints(), origin, ctx));
         return { width: 0, height: 0 };
     }
     getProps() {
-        return { children: this.children };
+        return { children: this.children, defaultTextStyle: this.defaultTextStyle };
     }
 }
-exports.PDFDocumentElement = PDFDocumentElement;

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

@@ -1,17 +1,77 @@
-import type { FontMetrics } from "../utils/font-metrics";
-import type { PDFPageConfig } from "./page-element";
-import type { BoxConstraints, Offset, Size } from "../layout/box-constraints";
+import type { FontMetrics } from "../utils/font-metrics.js";
+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.
  * `PageElement` sets `pageConfig` for its subtree, so each page flips against its own
  * height. The PDF byte writer is deliberately absent - layout must not touch it.
  */
+/**
+ * A positioning frame - the CSS "containing block" that `Positioned` children resolve their
+ * offsets against. A `relative` Box (later the page) creates one and threads it to its subtree;
+ * `Positioned` descendants register a placement closure in `place`, which the frame drains once it
+ * has finished sizing itself (so `right`/`bottom` can resolve against the final box).
+ */
+export interface PositioningFrame {
+    origin: Offset;
+    size: Size;
+    place: Array<(frame: {
+        origin: Offset;
+        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 {
+    /** 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;
+    };
+}
 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
+     *  from the built-in defaults + the `Document` defaults, and carried through page contexts; a
+     *  `Text` resolves its own unset properties against it. Absent falls back to the built-in defaults. */
+    textStyle?: ResolvedTextStyle;
+    /** 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;
+    get structId(): number;
+    /** Make this element share `from`'s tagging identity - used by fragmentation clones. Returns this. */
+    adoptStructId(from: PDFElement): this;
     abstract getProps(): unknown;
     /**
      * Lays the element out: `constraints` bound its size (flows DOWN), `offset` is the
@@ -20,6 +80,70 @@ 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;
+    /**
+     * 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;
@@ -32,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",
@@ -54,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

@@ -1,13 +1,110 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.VerticalAlignment = exports.HorizontalAlignment = exports.FlexiblePDFElement = exports.SizedPDFElement = exports.PDFElement = void 0;
-exports.isSizedElement = isSizedElement;
-exports.hasChildrenProp = hasChildrenProp;
-exports.hasChildProp = hasChildProp;
-class PDFElement {
+let _nextStructId = 0;
+export class PDFElement {
+    constructor() {
+        // Stable identity for accessible (PDF/UA) tagging: assigned once at construction and carried through
+        // fragmentation copies (adoptStructId), so a paragraph or table split across pages stays ONE structure
+        // element. Only the elements that actually tag (Text, Image, StructGroup) read it.
+        this._structId = _nextStructId++;
+        /**
+         * 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;
+    }
+    /** Make this element share `from`'s tagging identity - used by fragmentation clones. Returns this. */
+    adoptStructId(from) {
+        this._structId = from._structId;
+        return this;
+    }
+    /**
+     * The relative-size fraction (0..1) this element asked for on the given axis, if any (`horizontal` =
+     * width). A flex parent reads it to resolve a percentage child against its OWN main size - e.g. a
+     * `Box({ width: "50%" })` inside a Row, where the child otherwise gets an unbounded main axis and the
+     * fraction would have nothing to resolve against. Default: the element is not relatively sized.
+     */
+    relativeSizeFactor(_horizontal) {
+        return undefined;
+    }
+    /**
+     * Whether this element needs a BOUNDED extent on the given axis to lay itself out (`true` for a
+     * horizontal axis = width). A flex parent measures its fixed children with an unbounded main axis, so
+     * they keep their natural size; but a stack holding an `Expanded`/`Spacer` has no leftover space to
+     * distribute unless it is told how much main axis it may occupy. Such a stack answers `true` here and
+     * the parent hands it the line's bounded main extent instead of `Infinity`. Default: no.
+     */
+    needsBoundedMain(_horizontal) {
+        return false;
+    }
+    /**
+     * 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;
+    }
+    /** 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;
+    }
 }
-exports.PDFElement = PDFElement;
-class SizedPDFElement extends PDFElement {
+export class SizedPDFElement extends PDFElement {
     constructor(data) {
         super();
         this.x = data.x;
@@ -19,37 +116,58 @@ class SizedPDFElement extends PDFElement {
         return { x: this.x, y: this.y, width: this.width, height: this.height };
     }
 }
-exports.SizedPDFElement = SizedPDFElement;
-class FlexiblePDFElement extends PDFElement {
+export class FlexiblePDFElement extends PDFElement {
     constructor(data) {
         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;
+    }
 }
-exports.FlexiblePDFElement = FlexiblePDFElement;
-var HorizontalAlignment;
+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";
-})(HorizontalAlignment || (exports.HorizontalAlignment = HorizontalAlignment = {}));
-var VerticalAlignment;
+    /** 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) {
     VerticalAlignment["top"] = "TOP";
     VerticalAlignment["middle"] = "MIDDLE";
     VerticalAlignment["bottom"] = "BOTTOM";
-})(VerticalAlignment || (exports.VerticalAlignment = VerticalAlignment = {}));
-function isSizedElement(obj) {
+})(VerticalAlignment || (VerticalAlignment = {}));
+export function isSizedElement(obj) {
     return typeof obj === "object" && obj !== null && "x" in obj && "y" in obj;
 }
-function hasChildrenProp(obj) {
+export function hasChildrenProp(obj) {
     return "children" in obj;
 }
-function hasChildProp(obj) {
+export function hasChildProp(obj) {
     return "child" in obj;
 }