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

package/dist/api/layout.d.ts

@@ -1,14 +1,21 @@
-import { ContainerElement } from "../elements/container-element";
-import { RowElement } from "../elements/row-element";
-import { RectangleElement } from "../elements/rectangle-element";
-import { ExpandedElement } from "../elements/layout/expanded-element";
-import { PaddingElement } from "../elements/layout/padding-element";
-import { PDFElement } from "../elements/pdf-element";
-import { MainAlign, CrossAlign } from "../utils/flex-layout";
-import { ColorInput } from "./color";
-import { Insets } from "./insets";
+import { ExpandedElement } from "../elements/layout/expanded-element.js";
+import { PaddingElement } from "../elements/layout/padding-element.js";
+import { PageBreakElement } from "../elements/layout/page-break-element.js";
+import { KeepTogetherElement } from "../elements/layout/keep-together-element.js";
+import { PositionedElement, PositionedInsets } from "../elements/layout/positioned-element.js";
+import { LinkElement } from "../elements/layout/link-element.js";
+import { BookmarkElement } from "../elements/layout/bookmark-element.js";
+import { AnchorElement } from "../elements/layout/anchor-element.js";
+import { RotatedElement } from "../elements/layout/rotated-element.js";
+import { RotatedBoxElement } from "../elements/layout/rotated-box-element.js";
+import { PDFElement } from "../elements/pdf-element.js";
+import { MainAlign, CrossAlign } from "../utils/flex-layout.js";
+import { ColorInput } from "./color.js";
+import { type GradientInput } from "./gradient.js";
+import { Insets } from "./insets.js";
+import { BoundsInput, SizeInput, RadiusInput } from "./dimension.js";
 /** Options shared by the `Column` and `Row` stacks (locked §4). */
-export interface StackOptions {
+export interface StackOptions extends BoundsInput {
     /** Space inserted between children, in points. */
     gap?: number;
     /** Distribution along the main axis (CSS `justify-content`): start (default) · center · end ·
@@ -16,18 +23,45 @@ export interface StackOptions {
     justify?: MainAlign;
     /** Position across the axis (CSS `align-items`): start (default) · center · end · stretch. */
     align?: CrossAlign;
+    /** Size on each axis: points (fixed) or a percentage string like `"50%"` (a fraction of the offered
+     *  space). Omit to fill the offered width / shrink-wrap to the children. A percentage needs a bounded
+     *  axis (`height: "50%"` only resolves where the parent bounds the height). */
+    width?: SizeInput;
+    height?: SizeInput;
+    /** Start this stack on a fresh page (CSS `break-before: page`, react-pdf's `break`). Ignored at the
+     *  top of a page. */
+    breakBefore?: boolean;
+    /** Start everything after this stack on a fresh page (CSS `break-after: page`). */
+    breakAfter?: boolean;
+    /** Try to keep this stack on one page (CSS `break-inside: avoid`). If it does not fit here but would
+     *  fit on a fresh page, it moves there whole; if it is taller than a whole page, it splits anyway. */
+    keepTogether?: boolean;
+    /** Lay the children out backwards along the axis (CSS `row-reverse` / `column-reverse`). */
+    reverse?: boolean;
+    /** Let the children flow onto further lines when they do not fit (CSS `flex-wrap: wrap`). The `gap`
+     *  is used BETWEEN the lines as well as between the items. */
+    wrap?: boolean;
+    /** How the block of wrapped lines sits across the axis (CSS `align-content`). Default `start`. */
+    alignContent?: MainAlign;
 }
 /** A vertical stack. `Column(children)` or `Column(opts, children)`. */
-export declare function Column(children: PDFElement[]): ContainerElement;
-export declare function Column(opts: StackOptions, children: PDFElement[]): ContainerElement;
+export declare function Column(children: PDFElement[]): PDFElement;
+export declare function Column(opts: StackOptions, children: PDFElement[]): PDFElement;
 /** A horizontal stack. `Row(children)` or `Row(opts, children)`. */
-export declare function Row(children: PDFElement[]): RowElement;
-export declare function Row(opts: StackOptions, children: PDFElement[]): RowElement;
+export declare function Row(children: PDFElement[]): PDFElement;
+export declare function Row(opts: StackOptions, children: PDFElement[]): PDFElement;
+/**
+ * Keep a group of elements on ONE page (CSS `break-inside: avoid`). `keepTogether([...])` stacks the
+ * children in a `Column` and refuses to split them across a page break - unless they do not fit on a
+ * fresh page at all, in which case they split anyway (so pagination always terminates). Equivalent to
+ * the `keepTogether` prop on `Box`/`Column`/`Row`.
+ */
+export declare function keepTogether(children: PDFElement[]): KeepTogetherElement;
 /** A bordered / filled box that wraps its children (locked §4). */
-export interface BoxOptions {
-    /** Border (stroke) colour. A box has a border only when `border` or `borderWidth` is set. */
+export interface BoxOptions extends BoundsInput {
+    /** Border (stroke) color. A box has a border only when `border` or `borderWidth` is set. */
     border?: ColorInput;
-    /** Per-side border colours - override/add to `border`. Any of these makes the box draw
+    /** Per-side border colors - override/add to `border`. Any of these makes the box draw
      *  individual side lines (sharp corners) instead of a uniform frame - this is how you get
      *  grid lines (e.g. a cell with only `borderBottom` + `borderRight`). */
     borderTop?: ColorInput;
@@ -36,33 +70,123 @@ export interface BoxOptions {
     borderLeft?: ColorInput;
     /** Border thickness in points (default 1 when a border is present). */
     borderWidth?: number;
-    /** Background fill colour. */
-    bg?: ColorInput;
+    /** Background: a colour, or a gradient from `linearGradient()` / `radialGradient()`. */
+    bg?: ColorInput | GradientInput;
     /** Inner padding between the border and the children. */
     padding?: Insets;
-    /** Fixed size; omit to fill the offered width and shrink-wrap the height. */
-    width?: number;
-    height?: number;
+    /** Size on each axis: a number of points (fixed) or a percentage string like `"50%"` (a fraction
+     *  of the space the parent offers on that axis). Omit `width` to fill the offered width, omit
+     *  `height` to shrink-wrap the content. A percentage only resolves in a bounded region. */
+    width?: SizeInput;
+    height?: SizeInput;
     /** Corner radius in points. */
-    radius?: number;
+    radius?: RadiusInput;
+    /** Make this box a positioning frame: `Positioned` children placed inside it resolve their
+     *  offsets against this box (CSS `position: relative`). */
+    relative?: boolean;
+    /** `"hidden"` crops children to the box (rounded corners included); `"visible"` (default) lets a
+     *  `Positioned` child spill over the edge. */
+    overflow?: "hidden" | "visible";
+    /** Start this box on a fresh page (CSS `break-before: page`, react-pdf's `break`). Ignored at the top
+     *  of a page. */
+    breakBefore?: boolean;
+    /** Start everything after this box on a fresh page (CSS `break-after: page`). */
+    breakAfter?: boolean;
+    /** Try to keep this box on one page (CSS `break-inside: avoid`). Moves whole to a fresh page if it
+     *  would fit there; splits anyway if it is taller than a whole page. */
+    keepTogether?: boolean;
 }
 /**
  * A box: maps to a `RectangleElement` (fill + border + radius) whose children are stacked
  * inside it, optionally inset by `padding` (a `PaddingElement` wrapping a `Column` of the
  * children). With no `border`/`borderWidth` the box has no outline (`borderWidth` 0).
  */
-export declare function Box(children: PDFElement[]): RectangleElement;
-export declare function Box(opts: BoxOptions, children: PDFElement[]): RectangleElement;
+export declare function Box(children: PDFElement[]): PDFElement;
+export declare function Box(opts: BoxOptions, children: PDFElement[]): PDFElement;
 /** Insets a single child by `padding` (a number / `{x,y}` / `{top,…}` / 4-tuple). */
 export declare function Padding(padding: Insets, child: PDFElement): PaddingElement;
+/**
+ * Places a child OUT OF FLOW, relative to the nearest enclosing `relative` Box - or, with none, to
+ * the page's content box. Two ways, pick per axis: pin to EDGES - `Positioned({ top, left, right,
+ * bottom }, child)`, where a negative value pokes into / out of the corner (a badge, a tab, a
+ * ribbon) and pinning both sides stretches; or ANCHOR + nudge - `Positioned({ h: "center", v: "end",
+ * x: -10, y: -8 }, child)`, i.e. centered / end-aligned with a pixel offset. An edge wins over an
+ * anchor on the same axis.
+ *
+ * A `Positioned` in a `Page`'s `header` or `footer` repeats on EVERY page and takes no space in the
+ * band, which is how you draw a watermark, a draft stamp or a corner ribbon across a document. It
+ * anchors to the page, not to the band, so `bottom: 0` is the foot of the page.
+ */
+export declare function Positioned(opts: PositionedInsets, child: PDFElement): PositionedElement;
+/**
+ * Makes any `child` a clickable hyperlink - the child's whole box is the clickable region (an image, a
+ * box, a row). Pass `href` for an external URL, or `to` for an internal jump to an `Anchor({ name })`
+ * elsewhere in the document (e.g. a clickable table-of-contents row). Exactly one of the two. The link
+ * draws nothing itself, so style the child - e.g. `Link({ href }, Text("jasy.dev", { color: "#1450aa" }))`
+ * or `Link({ to: "chapter-2" }, Text("Chapter 2 ....... 5"))`. For a link on part of a line, put `href`/
+ * `to` on a `span` instead (`Text([span("Visit "), span("jasy.dev", { href })])`), linking just that run.
+ */
+export declare function Link(opts: {
+    href?: string;
+    to?: string;
+}, child: PDFElement): LinkElement;
+/**
+ * Marks `child` as a named jump target that an internal `Link({ to: name })` can point at (a table of
+ * contents linking to sections, cross-references). Layout-transparent: `child` renders exactly as it
+ * would on its own, on whatever page it lands on. `name` must match the link's `to`.
+ * `Anchor({ name: "chapter-2" }, Text("Chapter 2", { size: 24 }))`.
+ */
+export declare function Anchor(opts: {
+    name: string;
+}, child: PDFElement): AnchorElement;
+/**
+ * Adds a bookmark to the document outline (the viewer's sidebar) that jumps to `child`. `title` is the
+ * label; `level` (1-based, default 1) nests it - a `level: 2` bookmark hangs under the nearest preceding
+ * `level: 1`, so you get a collapsible tree (chapters -> sections). It is layout-transparent: `child`
+ * renders exactly as it would on its own. `Bookmark({ title: "Chapter 2", level: 1 }, Text("Chapter 2"))`.
+ */
+export declare function Bookmark(opts: {
+    title: string;
+    level?: number;
+}, child: PDFElement): BookmarkElement;
+/**
+ * Rotates `child` at PAINT time by `angle` degrees (clockwise), around its center - like CSS
+ * `transform: rotate()` / Flutter `Transform.rotate`. The child keeps its normal, unrotated layout box,
+ * so siblings do NOT reflow around the spun shape and the drawing may overflow its slot. Pair it with a
+ * `relative` Box + `Positioned` for a diagonal watermark or a "PAID" stamp laid over a document.
+ */
+export declare function Rotated(opts: {
+    angle: number;
+}, child: PDFElement): RotatedElement;
+/**
+ * Rotates `child` by whole quarter-turns and, unlike `Rotated`, is LAYOUT-AWARE: a 90 / 270 turn swaps
+ * the box's width and height so siblings reflow around it (a tall label becomes a narrow, tall strip
+ * that reserves exactly that footprint). `turns` = clockwise 90-degree steps (1 = 90, 2 = 180, 3 = 270).
+ * Use it for a vertical label beside a table; use `Rotated` for a free-angle stamp / watermark.
+ */
+export declare function RotatedBox(opts: {
+    turns: number;
+}, child: PDFElement): RotatedBoxElement;
 /**
  * A flexible empty gap that pushes its siblings apart - `Row([a, Spacer(), b])` sends `a`
  * and `b` to the edges. `flex` weights it against other flex children (default 1).
  */
 export declare function Spacer(flex?: number): ExpandedElement;
+/**
+ * A forced page break. Put it in a `Column` (or any vertical flow) and everything AFTER it starts on
+ * a fresh page, no matter how much space is left: `Column([intro, PageBreak(), chapterTwo])`. It takes
+ * no space and draws nothing. Works nested, and a break wins over `keepTogether`.
+ */
+export declare function PageBreak(): PageBreakElement;
 export interface ExpandedOptions {
     /** Share of the leftover space vs other flex children (default 1). */
     flex?: number;
+    /**
+     * Main-axis size reserved BEFORE the leftover is shared out (CSS `flex-basis`): points, or a
+     * percentage of what the line offers its items. The child ends up with `basis + its share of the
+     * rest`, so `flexBasis: 120` with `flex: 0` is simply a fixed 120pt slot. Default 0.
+     */
+    flexBasis?: SizeInput;
 }
 /**
  * Makes a child fill the leftover space along the stack's main axis (height in a Column,

package/dist/api/layout.js

@@ -1,74 +1,123 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Column = Column;
-exports.Row = Row;
-exports.Box = Box;
-exports.Padding = Padding;
-exports.Spacer = Spacer;
-exports.Expanded = Expanded;
-const container_element_1 = require("../elements/container-element");
-const row_element_1 = require("../elements/row-element");
-const rectangle_element_1 = require("../elements/rectangle-element");
-const expanded_element_1 = require("../elements/layout/expanded-element");
-const padding_element_1 = require("../elements/layout/padding-element");
-const color_1 = require("./color");
-const insets_1 = require("./insets");
-const args_1 = require("./args");
+import { ContainerElement } from "../elements/container-element.js";
+import { RowElement } from "../elements/row-element.js";
+import { RectangleElement } from "../elements/rectangle-element.js";
+import { ExpandedElement } from "../elements/layout/expanded-element.js";
+import { PaddingElement } from "../elements/layout/padding-element.js";
+import { PageBreakElement } from "../elements/layout/page-break-element.js";
+import { KeepTogetherElement } from "../elements/layout/keep-together-element.js";
+import { PositionedElement } from "../elements/layout/positioned-element.js";
+import { LinkElement } from "../elements/layout/link-element.js";
+import { BookmarkElement } from "../elements/layout/bookmark-element.js";
+import { AnchorElement } from "../elements/layout/anchor-element.js";
+import { RotatedElement } from "../elements/layout/rotated-element.js";
+import { RotatedBoxElement } from "../elements/layout/rotated-box-element.js";
+import { toColor } from "./color.js";
+import { isGradientInput } from "./gradient.js";
+import { toEdges } from "./insets.js";
+import { toBounds, toDimension, toRadius, } from "./dimension.js";
+import { splitArgs } from "./args.js";
+/** Splits `StackOptions` width/height into the fixed points + fraction the stack elements expect. */
+function stackSize(opts) {
+    const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
+    const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
+    return {
+        width: w?.points,
+        height: h?.points,
+        widthFactor: w?.factor,
+        heightFactor: h?.factor,
+        ...toBounds(opts),
+    };
+}
 // The public default for `cross` is `start` (locked §5) - i.e. don't stretch a child unless
 // asked. The engine default is `stretch`; the factory sets the friendlier public one.
 const DEFAULT_CROSS = "start";
-function Column(a, b) {
-    var _a;
-    const { opts, children } = (0, args_1.splitArgs)(a, b);
-    return new container_element_1.ContainerElement({
+export function Column(a, b) {
+    const { opts, children } = splitArgs(a, b);
+    return maybeKeepTogether(opts, new ContainerElement({
         x: 0,
         y: 0,
         children,
         gap: opts.gap,
         main: opts.justify, // undefined → engine default `start` (matches §5)
-        cross: (_a = opts.align) !== null && _a !== void 0 ? _a : DEFAULT_CROSS,
-    });
+        cross: opts.align ?? DEFAULT_CROSS,
+        reverse: opts.reverse,
+        wrap: opts.wrap,
+        alignContent: opts.alignContent,
+        breakBefore: opts.breakBefore,
+        breakAfter: opts.breakAfter,
+        ...stackSize(opts),
+    }));
 }
-function Row(a, b) {
-    var _a;
-    const { opts, children } = (0, args_1.splitArgs)(a, b);
-    return new row_element_1.RowElement({
+export function Row(a, b) {
+    const { opts, children } = splitArgs(a, b);
+    return maybeKeepTogether(opts, new RowElement({
         children,
         gap: opts.gap,
         main: opts.justify,
-        cross: (_a = opts.align) !== null && _a !== void 0 ? _a : DEFAULT_CROSS,
-    });
+        cross: opts.align ?? DEFAULT_CROSS,
+        reverse: opts.reverse,
+        wrap: opts.wrap,
+        alignContent: opts.alignContent,
+        breakBefore: opts.breakBefore,
+        breakAfter: opts.breakAfter,
+        ...stackSize(opts),
+    }));
+}
+/** Wraps `element` in a `keepTogether` group when the `keepTogether` option is set; otherwise returns it
+ *  unchanged (byte-identical). Shared by the `Box`/`Column`/`Row` prop shortcut. */
+function maybeKeepTogether(opts, element) {
+    // alignSelf and order go on the OUTERMOST element - that is the one the surrounding stack places.
+    const wrapped = opts.keepTogether ? new KeepTogetherElement({ child: element }) : element;
+    return wrapped
+        .withAlignSelf(opts.alignSelf)
+        .withOrder(opts.order)
+        .withFlexShrink(opts.flexShrink);
+}
+/**
+ * Keep a group of elements on ONE page (CSS `break-inside: avoid`). `keepTogether([...])` stacks the
+ * children in a `Column` and refuses to split them across a page break - unless they do not fit on a
+ * fresh page at all, in which case they split anyway (so pagination always terminates). Equivalent to
+ * the `keepTogether` prop on `Box`/`Column`/`Row`.
+ */
+export function keepTogether(children) {
+    const child = children.length === 1 ? children[0] : Column(children);
+    return new KeepTogetherElement({ child });
 }
-function Box(a, b) {
-    var _a;
-    const { opts, children } = (0, args_1.splitArgs)(a, b);
+export function Box(a, b) {
+    const { opts, children } = splitArgs(a, b);
     const content = opts.padding !== undefined && children.length > 0
         ? [
-            new padding_element_1.PaddingElement({
-                margin: (0, insets_1.toEdges)(opts.padding),
+            new PaddingElement({
+                margin: toEdges(opts.padding),
                 child: children.length === 1 ? children[0] : Column(children),
             }),
         ]
         : children;
     // A side is set if it (or the uniform `border`) is given. If ANY differs from a plain
-    // uniform border, we hand the engine per-side colours (which draws individual lines).
+    // uniform border, we hand the engine per-side colors (which draws individual lines).
     const sideKeys = [opts.borderTop, opts.borderRight, opts.borderBottom, opts.borderLeft];
     const hasPerSide = sideKeys.some((s) => s !== undefined);
     const side = (s) => {
-        const c = s !== null && s !== void 0 ? s : opts.border;
-        return c !== undefined ? (0, color_1.toColor)(c) : undefined;
+        const c = s ?? opts.border;
+        return c !== undefined ? toColor(c) : undefined;
     };
     const hasBorder = opts.border !== undefined || opts.borderWidth !== undefined || hasPerSide;
-    return new rectangle_element_1.RectangleElement({
+    // A point size fills `width`/`height`; a percentage fills `widthFactor`/`heightFactor`.
+    const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
+    const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
+    return maybeKeepTogether(opts, new RectangleElement({
         x: 0,
         y: 0,
         children: content,
-        color: opts.border !== undefined ? (0, color_1.toColor)(opts.border) : undefined,
-        backgroundColor: opts.bg !== undefined ? (0, color_1.toColor)(opts.bg) : undefined,
-        borderWidth: hasBorder ? ((_a = opts.borderWidth) !== null && _a !== void 0 ? _a : 1) : 0,
-        width: opts.width,
-        height: opts.height,
-        radius: opts.radius,
+        color: opts.border !== undefined ? toColor(opts.border) : undefined,
+        backgroundColor: opts.bg === undefined ? undefined : isGradientInput(opts.bg) ? opts.bg : toColor(opts.bg),
+        borderWidth: hasBorder ? (opts.borderWidth ?? 1) : 0,
+        width: w?.points,
+        height: h?.points,
+        widthFactor: w?.factor,
+        heightFactor: h?.factor,
+        ...toBounds(opts),
+        radius: opts.radius !== undefined ? toRadius(opts.radius) : undefined,
         sideBorders: hasPerSide
             ? {
                 top: side(opts.borderTop),
@@ -77,23 +126,105 @@ function Box(a, b) {
                 left: side(opts.borderLeft),
             }
             : undefined,
-    });
+        relative: opts.relative,
+        overflow: opts.overflow,
+        breakBefore: opts.breakBefore,
+        breakAfter: opts.breakAfter,
+    }));
 }
 /** Insets a single child by `padding` (a number / `{x,y}` / `{top,…}` / 4-tuple). */
-function Padding(padding, child) {
-    return new padding_element_1.PaddingElement({ margin: (0, insets_1.toEdges)(padding), child });
+export function Padding(padding, child) {
+    return new PaddingElement({ margin: toEdges(padding), child });
+}
+/**
+ * Places a child OUT OF FLOW, relative to the nearest enclosing `relative` Box - or, with none, to
+ * the page's content box. Two ways, pick per axis: pin to EDGES - `Positioned({ top, left, right,
+ * bottom }, child)`, where a negative value pokes into / out of the corner (a badge, a tab, a
+ * ribbon) and pinning both sides stretches; or ANCHOR + nudge - `Positioned({ h: "center", v: "end",
+ * x: -10, y: -8 }, child)`, i.e. centered / end-aligned with a pixel offset. An edge wins over an
+ * anchor on the same axis.
+ *
+ * A `Positioned` in a `Page`'s `header` or `footer` repeats on EVERY page and takes no space in the
+ * band, which is how you draw a watermark, a draft stamp or a corner ribbon across a document. It
+ * anchors to the page, not to the band, so `bottom: 0` is the foot of the page.
+ */
+export function Positioned(opts, child) {
+    return new PositionedElement({ child, ...opts });
+}
+/**
+ * Makes any `child` a clickable hyperlink - the child's whole box is the clickable region (an image, a
+ * box, a row). Pass `href` for an external URL, or `to` for an internal jump to an `Anchor({ name })`
+ * elsewhere in the document (e.g. a clickable table-of-contents row). Exactly one of the two. The link
+ * draws nothing itself, so style the child - e.g. `Link({ href }, Text("jasy.dev", { color: "#1450aa" }))`
+ * or `Link({ to: "chapter-2" }, Text("Chapter 2 ....... 5"))`. For a link on part of a line, put `href`/
+ * `to` on a `span` instead (`Text([span("Visit "), span("jasy.dev", { href })])`), linking just that run.
+ */
+export function Link(opts, child) {
+    if ((opts.href === undefined) === (opts.to === undefined)) {
+        throw new Error("Link needs exactly one of `href` (external URL) or `to` (internal Anchor name).");
+    }
+    return new LinkElement({ href: opts.href, dest: opts.to, child });
+}
+/**
+ * Marks `child` as a named jump target that an internal `Link({ to: name })` can point at (a table of
+ * contents linking to sections, cross-references). Layout-transparent: `child` renders exactly as it
+ * would on its own, on whatever page it lands on. `name` must match the link's `to`.
+ * `Anchor({ name: "chapter-2" }, Text("Chapter 2", { size: 24 }))`.
+ */
+export function Anchor(opts, child) {
+    return new AnchorElement({ name: opts.name, child });
+}
+/**
+ * Adds a bookmark to the document outline (the viewer's sidebar) that jumps to `child`. `title` is the
+ * label; `level` (1-based, default 1) nests it - a `level: 2` bookmark hangs under the nearest preceding
+ * `level: 1`, so you get a collapsible tree (chapters -> sections). It is layout-transparent: `child`
+ * renders exactly as it would on its own. `Bookmark({ title: "Chapter 2", level: 1 }, Text("Chapter 2"))`.
+ */
+export function Bookmark(opts, child) {
+    return new BookmarkElement({ title: opts.title, level: opts.level, child });
+}
+/**
+ * Rotates `child` at PAINT time by `angle` degrees (clockwise), around its center - like CSS
+ * `transform: rotate()` / Flutter `Transform.rotate`. The child keeps its normal, unrotated layout box,
+ * so siblings do NOT reflow around the spun shape and the drawing may overflow its slot. Pair it with a
+ * `relative` Box + `Positioned` for a diagonal watermark or a "PAID" stamp laid over a document.
+ */
+export function Rotated(opts, child) {
+    return new RotatedElement({ angle: opts.angle, child });
+}
+/**
+ * Rotates `child` by whole quarter-turns and, unlike `Rotated`, is LAYOUT-AWARE: a 90 / 270 turn swaps
+ * the box's width and height so siblings reflow around it (a tall label becomes a narrow, tall strip
+ * that reserves exactly that footprint). `turns` = clockwise 90-degree steps (1 = 90, 2 = 180, 3 = 270).
+ * Use it for a vertical label beside a table; use `Rotated` for a free-angle stamp / watermark.
+ */
+export function RotatedBox(opts, child) {
+    return new RotatedBoxElement({ turns: opts.turns, child });
 }
 /**
  * A flexible empty gap that pushes its siblings apart - `Row([a, Spacer(), b])` sends `a`
  * and `b` to the edges. `flex` weights it against other flex children (default 1).
  */
-function Spacer(flex = 1) {
-    return new expanded_element_1.ExpandedElement({ flex, child: Column([]) });
+export function Spacer(flex = 1) {
+    return new ExpandedElement({ flex, child: Column([]) });
 }
-function Expanded(a, b) {
-    var _a;
+/**
+ * A forced page break. Put it in a `Column` (or any vertical flow) and everything AFTER it starts on
+ * a fresh page, no matter how much space is left: `Column([intro, PageBreak(), chapterTwo])`. It takes
+ * no space and draws nothing. Works nested, and a break wins over `keepTogether`.
+ */
+export function PageBreak() {
+    return new PageBreakElement();
+}
+export function Expanded(a, b) {
     const isOptsForm = b !== undefined;
     const opts = (isOptsForm ? a : {});
     const child = (isOptsForm ? b : a);
-    return new expanded_element_1.ExpandedElement({ flex: (_a = opts.flex) !== null && _a !== void 0 ? _a : 1, child });
+    const basis = opts.flexBasis !== undefined ? toDimension(opts.flexBasis) : undefined;
+    return new ExpandedElement({
+        flex: opts.flex ?? 1,
+        basis: basis?.points,
+        basisFactor: basis?.factor,
+        child,
+    });
 }

package/dist/api/page-builder.d.ts

@@ -0,0 +1,40 @@
+import { PageBuilderElement } from "../elements/layout/page-builder-element.js";
+import { PageInfo, PDFElement } from "../elements/pdf-element.js";
+import { TextOptions } from "./text.js";
+export type { PageInfo };
+/**
+ * Builds content from the page it ends up on - this is how you show `pageNumber` / `pageCount`. Place it
+ * anywhere: in a `Page`'s `header`/`footer`, in the body, in a table cell, several times on one page.
+ * Because you write the closure, formatting and conditions are yours:
+ *
+ * ```ts
+ * PageBuilder(({ pageNumber, pageCount }) => Text(`Seite ${pageNumber} von ${pageCount}`))
+ * PageBuilder(({ pageNumber }) => (pageNumber === 1 ? Logo() : Text("Fortsetzung")))
+ * PageBuilder(({ pageNumber, pageCount }) => Text(`${pageNumber - 1} / ${pageCount - 1}`)) // cover page
+ * ```
+ *
+ * `pageNumber` is 1-based and counts PHYSICAL pages (an overflowing `Page` contributes several);
+ * `pageCount` is the document total; `pageSize` is the media box in points.
+ *
+ * `subPageNumber` / `subPageTotalPages` are the same counts WITHIN one logical `Page` element - what you
+ * want when a document is several sections and the footer should say "Attachment, page 1 of 4" beside
+ * "sheet 4 of 7". With a single `Page` they are identical to the document counts.
+ *
+ * The numbers themselves are always exact. Two sizing caveats, both from the same chicken-and-egg (the
+ * content decides the count that the content displays): in the flowing BODY the box is reserved before the
+ * total is known, so a much wider final string can paint slightly past it; and a conditional header may
+ * SHRINK on later pages but must not GROW, because the body band was measured against the first build.
+ */
+export declare function PageBuilder(build: (info: PageInfo) => PDFElement): PageBuilderElement;
+/** `Text` options plus an `offset` added to the number (e.g. `-1` to not count a cover page). */
+export interface PageNumberOptions extends TextOptions {
+    offset?: number;
+}
+/** The current page number as text. Sugar for `PageBuilder` - same thing, one word. */
+export declare function PageNumber({ offset, ...style }?: PageNumberOptions): PageBuilderElement;
+/** The document's total page count as text. Sugar for `PageBuilder`. */
+export declare function PageCount({ offset, ...style }?: PageNumberOptions): PageBuilderElement;
+/** The page number WITHIN its logical `Page` (a section), as text. Sugar for `PageBuilder`. */
+export declare function SubPageNumber({ offset, ...style }?: PageNumberOptions): PageBuilderElement;
+/** How many pages the surrounding logical `Page` produced, as text. Sugar for `PageBuilder`. */
+export declare function SubPageCount({ offset, ...style }?: PageNumberOptions): PageBuilderElement;

package/dist/api/page-builder.js

@@ -0,0 +1,44 @@
+import { PageBuilderElement } from "../elements/layout/page-builder-element.js";
+import { Text } from "./text.js";
+/**
+ * Builds content from the page it ends up on - this is how you show `pageNumber` / `pageCount`. Place it
+ * anywhere: in a `Page`'s `header`/`footer`, in the body, in a table cell, several times on one page.
+ * Because you write the closure, formatting and conditions are yours:
+ *
+ * ```ts
+ * PageBuilder(({ pageNumber, pageCount }) => Text(`Seite ${pageNumber} von ${pageCount}`))
+ * PageBuilder(({ pageNumber }) => (pageNumber === 1 ? Logo() : Text("Fortsetzung")))
+ * PageBuilder(({ pageNumber, pageCount }) => Text(`${pageNumber - 1} / ${pageCount - 1}`)) // cover page
+ * ```
+ *
+ * `pageNumber` is 1-based and counts PHYSICAL pages (an overflowing `Page` contributes several);
+ * `pageCount` is the document total; `pageSize` is the media box in points.
+ *
+ * `subPageNumber` / `subPageTotalPages` are the same counts WITHIN one logical `Page` element - what you
+ * want when a document is several sections and the footer should say "Attachment, page 1 of 4" beside
+ * "sheet 4 of 7". With a single `Page` they are identical to the document counts.
+ *
+ * The numbers themselves are always exact. Two sizing caveats, both from the same chicken-and-egg (the
+ * content decides the count that the content displays): in the flowing BODY the box is reserved before the
+ * total is known, so a much wider final string can paint slightly past it; and a conditional header may
+ * SHRINK on later pages but must not GROW, because the body band was measured against the first build.
+ */
+export function PageBuilder(build) {
+    return new PageBuilderElement({ build });
+}
+/** The current page number as text. Sugar for `PageBuilder` - same thing, one word. */
+export function PageNumber({ offset = 0, ...style } = {}) {
+    return PageBuilder(({ pageNumber }) => Text(String(pageNumber + offset), style));
+}
+/** The document's total page count as text. Sugar for `PageBuilder`. */
+export function PageCount({ offset = 0, ...style } = {}) {
+    return PageBuilder(({ pageCount }) => Text(String(pageCount + offset), style));
+}
+/** The page number WITHIN its logical `Page` (a section), as text. Sugar for `PageBuilder`. */
+export function SubPageNumber({ offset = 0, ...style } = {}) {
+    return PageBuilder(({ subPageNumber }) => Text(String(subPageNumber + offset), style));
+}
+/** How many pages the surrounding logical `Page` produced, as text. Sugar for `PageBuilder`. */
+export function SubPageCount({ offset = 0, ...style } = {}) {
+    return PageBuilder(({ subPageTotalPages }) => Text(String(subPageTotalPages + offset), style));
+}