@jasy/pdf 1.0.0-alpha.1

package/dist/api/insets.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toEdges = toEdges;
+/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`. */
+function toEdges(i) {
+    var _a, _b, _c, _d, _e, _f;
+    if (typeof i === "number")
+        return [i, i, i, i];
+    if (Array.isArray(i))
+        return i;
+    // Axis form ({x, y}) and per-side form ({top,...}) are both all-optional objects (TS
+    // can't discriminate them), so read through one shape: an axis key present picks the
+    // axis interpretation (an empty object is all-zero either way).
+    const o = i;
+    if (o.x !== undefined || o.y !== undefined) {
+        const x = (_a = o.x) !== null && _a !== void 0 ? _a : 0;
+        const y = (_b = o.y) !== null && _b !== void 0 ? _b : 0;
+        return [y, x, y, x];
+    }
+    return [(_c = o.top) !== null && _c !== void 0 ? _c : 0, (_d = o.right) !== null && _d !== void 0 ? _d : 0, (_e = o.bottom) !== null && _e !== void 0 ? _e : 0, (_f = o.left) !== null && _f !== void 0 ? _f : 0];
+}

package/dist/api/layout.d.ts

@@ -0,0 +1,72 @@
+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";
+/** Options shared by the `Column` and `Row` stacks (locked §4). */
+export interface StackOptions {
+    /** Space inserted between children, in points. */
+    gap?: number;
+    /** Distribution along the main axis (CSS `justify-content`): start (default) · center · end ·
+     *  between · around. */
+    justify?: MainAlign;
+    /** Position across the axis (CSS `align-items`): start (default) · center · end · stretch. */
+    align?: CrossAlign;
+}
+/** 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;
+/** 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;
+/** 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. */
+    border?: ColorInput;
+    /** Per-side border colours - 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;
+    borderRight?: ColorInput;
+    borderBottom?: ColorInput;
+    borderLeft?: ColorInput;
+    /** Border thickness in points (default 1 when a border is present). */
+    borderWidth?: number;
+    /** Background fill colour. */
+    bg?: ColorInput;
+    /** 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;
+    /** Corner radius in points. */
+    radius?: number;
+}
+/**
+ * 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;
+/** Insets a single child by `padding` (a number / `{x,y}` / `{top,…}` / 4-tuple). */
+export declare function Padding(padding: Insets, child: PDFElement): PaddingElement;
+/**
+ * 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;
+export interface ExpandedOptions {
+    /** Share of the leftover space vs other flex children (default 1). */
+    flex?: number;
+}
+/**
+ * Makes a child fill the leftover space along the stack's main axis (height in a Column,
+ * width in a Row). `Expanded(child)` or `Expanded({ flex }, child)`.
+ */
+export declare function Expanded(child: PDFElement): ExpandedElement;
+export declare function Expanded(opts: ExpandedOptions, child: PDFElement): ExpandedElement;

package/dist/api/layout.js

@@ -0,0 +1,99 @@
+"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");
+// 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({
+        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,
+    });
+}
+function Row(a, b) {
+    var _a;
+    const { opts, children } = (0, args_1.splitArgs)(a, b);
+    return new row_element_1.RowElement({
+        children,
+        gap: opts.gap,
+        main: opts.justify,
+        cross: (_a = opts.align) !== null && _a !== void 0 ? _a : DEFAULT_CROSS,
+    });
+}
+function Box(a, b) {
+    var _a;
+    const { opts, children } = (0, args_1.splitArgs)(a, b);
+    const content = opts.padding !== undefined && children.length > 0
+        ? [
+            new padding_element_1.PaddingElement({
+                margin: (0, insets_1.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).
+    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 hasBorder = opts.border !== undefined || opts.borderWidth !== undefined || hasPerSide;
+    return new rectangle_element_1.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,
+        sideBorders: hasPerSide
+            ? {
+                top: side(opts.borderTop),
+                right: side(opts.borderRight),
+                bottom: side(opts.borderBottom),
+                left: side(opts.borderLeft),
+            }
+            : undefined,
+    });
+}
+/** 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 });
+}
+/**
+ * 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([]) });
+}
+function Expanded(a, b) {
+    var _a;
+    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 });
+}

package/dist/api/structure.d.ts

@@ -0,0 +1,80 @@
+import { PDFDocumentElement } from "../elements/pdf-document-element";
+import { PageElement } from "../elements/page-element";
+import { PDFElement } from "../elements/pdf-element";
+import { PageSize } from "../constants/page-sizes";
+import { StackOptions } from "./layout";
+import { Insets } from "./insets";
+/** A page size: a `PageSize` enum, or a friendly name like `"A4"` / `"letter"` (any case). */
+export type PageSizeInput = PageSize | string;
+export interface PageOptions extends StackOptions {
+    /** Page size (default A4). */
+    size?: PageSizeInput;
+    orientation?: "portrait" | "landscape";
+    /** Page margin (default 56pt all sides). */
+    margin?: Insets;
+    /** Laid out at the top, repeated on every physical page. */
+    header?: PDFElement;
+    /** Laid out at the bottom, repeated on every physical page. */
+    footer?: PDFElement;
+}
+/**
+ * One page template. `Page(children)` or `Page(opts, children)`. The children are stacked
+ * (auto-wrapped in a `Column`, locked §6) inside the content box; `header`/`footer` repeat
+ * on every physical page the content paginates onto.
+ */
+export declare function Page(children: PDFElement[]): PageElement;
+export declare function Page(opts: PageOptions, children: PDFElement[]): PageElement;
+export interface DocumentOptions {
+    /** PDF metadata. */
+    meta?: {
+        title?: string;
+        author?: string;
+    };
+}
+/** The document root. `Document(pages)` or `Document(opts, pages)`. */
+export declare function Document(pages: PageElement[]): PDFDocumentElement;
+export declare function Document(opts: DocumentOptions, pages: PageElement[]): PDFDocumentElement;
+export type FontBytes = Buffer | Uint8Array;
+/** A font family: one `.ttf` per style. Only `normal` is required; `bold`/`italic`/`boldItalic`
+ *  are picked up automatically by `Text({ bold, italic })`, falling back to `normal` if absent. */
+export interface FontFamily {
+    normal: FontBytes;
+    bold?: FontBytes;
+    italic?: FontBytes;
+    boldItalic?: FontBytes;
+}
+/** A file to embed in the PDF as an associated file (PDF/A-3 / PDF 2.0). */
+export interface Attachment {
+    /** Display file name, e.g. `"factur-x.xml"`. */
+    name: string;
+    data: FontBytes;
+    /** `/AFRelationship`, e.g. `"Data"` (ZUGFeRD), `"Source"`, `"Alternative"`. Default `"Unspecified"`. */
+    relationship?: string;
+    /** MIME type, e.g. `"text/xml"`. Default `"application/octet-stream"`. */
+    mimeType?: string;
+    description?: string;
+}
+export interface RenderOptions {
+    /** Embedded TrueType fonts, keyed by the name used in `Text({ font })`. The value is either the
+     *  raw `.ttf` bytes (registered as `normal`) or a `FontFamily` with per-style files. */
+    fonts?: Record<string, FontBytes | FontFamily>;
+    /** Files to embed as associated files (e.g. the ZUGFeRD `factur-x.xml`). */
+    attachments?: Attachment[];
+    /** Document XMP metadata packet (catalog `/Metadata`), e.g. PDF/A-3 + Factur-X. Keep it ASCII. */
+    xmp?: string;
+    /** ICC profile bytes for a PDF/A `/OutputIntent` (an RGB profile, e.g. sRGB). */
+    outputIntent?: FontBytes;
+    /** PDF header version, e.g. `"1.7"` for PDF/A-3 (default `"1.4"`). */
+    pdfVersion?: string;
+    /** Write a trailer `/ID` (required by PDF/A); the id is a deterministic content hash. */
+    documentId?: boolean;
+    /** Register the standard-14 fonts (default true). Set false for PDF/A so only embedded fonts
+     *  appear - then every font name used must be supplied via `fonts`. */
+    standardFonts?: boolean;
+    /** FlateDecode-compress the streams (default true). Set false for a greppable, uncompressed PDF. */
+    compress?: boolean;
+}
+/** Renders a `Document(...)` tree to the raw PDF string. */
+export declare function renderPdf(doc: PDFDocumentElement, options?: RenderOptions): Promise<string>;
+/** Renders a `Document(...)` tree to PDF bytes (e.g. for a download / save dialog). */
+export declare function renderToBytes(doc: PDFDocumentElement, options?: RenderOptions): Promise<Uint8Array>;

package/dist/api/structure.js

@@ -0,0 +1,125 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Page = Page;
+exports.Document = Document;
+exports.renderPdf = renderPdf;
+exports.renderToBytes = renderToBytes;
+const pdf_document_element_1 = require("../elements/pdf-document-element");
+const page_element_1 = require("../elements/page-element");
+const page_sizes_1 = require("../constants/page-sizes");
+const pdf_config_1 = require("../renderer/pdf-config");
+const pdf_document_class_1 = require("../renderer/pdf-document-class");
+const pdf_object_manager_1 = require("../utils/pdf-object-manager");
+const utf8_to_windows1252_encoder_1 = require("../utils/utf8-to-windows1252-encoder");
+const layout_1 = require("./layout");
+const insets_1 = require("./insets");
+const PAGE_SIZE_VALUES = new Set(Object.values(page_sizes_1.PageSize));
+function toPageSize(input) {
+    const v = String(input).toLowerCase();
+    if (!PAGE_SIZE_VALUES.has(v))
+        throw new Error(`Unknown page size: "${input}"`);
+    return v;
+}
+/** Default page margin (all sides, points) when a `Page` doesn't set one. */
+const DEFAULT_MARGIN = 56;
+function Page(a, b) {
+    var _a;
+    const isOpts = !Array.isArray(a);
+    const opts = (isOpts ? a : {});
+    const children = (isOpts ? (b !== null && b !== void 0 ? b : []) : a);
+    const [top, right, bottom, left] = (0, insets_1.toEdges)((_a = opts.margin) !== null && _a !== void 0 ? _a : DEFAULT_MARGIN);
+    const config = {
+        pageSize: opts.size !== undefined ? toPageSize(opts.size) : page_sizes_1.PageSize.A4,
+        orientation: opts.orientation === "landscape" ? pdf_config_1.Orientation.landscape : pdf_config_1.Orientation.portrait,
+        margin: { top, right, bottom, left },
+    };
+    return new page_element_1.PageElement({
+        config,
+        header: opts.header,
+        footer: opts.footer,
+        children: [(0, layout_1.Column)({ gap: opts.gap, justify: opts.justify, align: opts.align }, children)],
+    });
+}
+// Document metadata is a document-render concern, not part of the element tree, so it is
+// kept beside the returned element and picked up by `renderPdf`.
+const docMeta = new WeakMap();
+function Document(a, b) {
+    const isOpts = !Array.isArray(a);
+    const opts = (isOpts ? a : {});
+    const pages = (isOpts ? (b !== null && b !== void 0 ? b : []) : a);
+    const doc = new pdf_document_element_1.PDFDocumentElement({ children: pages });
+    if (opts.meta)
+        docMeta.set(doc, opts.meta);
+    return doc;
+}
+function isFontBytes(v) {
+    return Buffer.isBuffer(v) || v instanceof Uint8Array;
+}
+/** Renders a `Document(...)` tree to the raw PDF string. */
+function renderPdf(doc, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const meta = docMeta.get(doc);
+        const config = Object.assign(Object.assign({}, (meta ? { metaData: { title: meta.title, author: meta.author, keywords: [] } } : {})), ((options === null || options === void 0 ? void 0 : options.standardFonts) === false ? { registerStandardFonts: false } : {}));
+        const fonts = (_a = options === null || options === void 0 ? void 0 : options.fonts) !== null && _a !== void 0 ? _a : {};
+        const attachments = (_b = options === null || options === void 0 ? void 0 : options.attachments) !== null && _b !== void 0 ? _b : [];
+        // A throwaway PDFDocument whose build() yields this tree, reusing the engine's standard
+        // font registration + config handling (the constructor does both). Custom fonts are
+        // registered here, before layout/render, so both the metrics and the backend see them.
+        const Anon = class extends pdf_document_class_1.PDFDocument {
+            constructor() {
+                super(config);
+                const om = this.objectManager;
+                om.setCompress((options === null || options === void 0 ? void 0 : options.compress) !== false); // FlateDecode streams by default
+                for (const [name, value] of Object.entries(fonts)) {
+                    if (isFontBytes(value)) {
+                        om.registerCustomFont(name, Buffer.from(value));
+                    }
+                    else {
+                        om.registerCustomFont(name, Buffer.from(value.normal), pdf_object_manager_1.FontStyle.Normal);
+                        if (value.bold)
+                            om.registerCustomFont(name, Buffer.from(value.bold), pdf_object_manager_1.FontStyle.Bold);
+                        if (value.italic)
+                            om.registerCustomFont(name, Buffer.from(value.italic), pdf_object_manager_1.FontStyle.Italic);
+                        if (value.boldItalic)
+                            om.registerCustomFont(name, Buffer.from(value.boldItalic), pdf_object_manager_1.FontStyle.BoldItalic);
+                    }
+                }
+                for (const a of attachments) {
+                    om.attachFile(a.name, Buffer.from(a.data), {
+                        relationship: a.relationship,
+                        mimeType: a.mimeType,
+                        description: a.description,
+                    });
+                }
+                if (options === null || options === void 0 ? void 0 : options.xmp)
+                    om.setXmpMetadata(options.xmp);
+                if (options === null || options === void 0 ? void 0 : options.outputIntent)
+                    om.setOutputIntent(Buffer.from(options.outputIntent));
+                if (options === null || options === void 0 ? void 0 : options.pdfVersion)
+                    om.setPdfVersion(options.pdfVersion);
+                if (options === null || options === void 0 ? void 0 : options.documentId)
+                    om.enableDocumentId();
+            }
+            build() {
+                return doc;
+            }
+        };
+        return Anon.render();
+    });
+}
+/** Renders a `Document(...)` tree to PDF bytes (e.g. for a download / save dialog). */
+function renderToBytes(doc, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return new Uint8Array((0, utf8_to_windows1252_encoder_1.getArrayBuffer)(yield renderPdf(doc, options)));
+    });
+}

package/dist/api/table.d.ts

@@ -0,0 +1,37 @@
+import { PDFElement } from "../elements/pdf-element";
+import { Insets } from "./insets";
+import { ColorInput } from "./color";
+/**
+ * A column width: a `number` of points (fixed), an `"Nfr"` fraction (splits the leftover
+ * width), or `"auto"` (as wide as the widest cell in that column - measured at layout time).
+ */
+export type ColumnWidth = number | string;
+/** A table cell: any element, or a string (wrapped in `Text`). */
+export type Cell = PDFElement | string;
+export interface TableOptions {
+    /** One entry per column: a fixed point width, an `"Nfr"` fraction, or `"auto"`. */
+    columns: ColumnWidth[];
+    /** A header row that REPEATS at the top of every page the table flows onto. */
+    header?: Cell[];
+    /** Gap between both columns and rows (default 0). */
+    gap?: number;
+    /** Gap between rows (overrides `gap`). */
+    rowGap?: number;
+    /** Gap between columns (overrides `gap`). */
+    colGap?: number;
+    /** Padding inside every cell (default none). */
+    cellPadding?: Insets;
+    /** Grid line colour around every cell. Draws the complete grid once - don't add your own
+     *  frame Box, or the outer edges double up. */
+    cellBorder?: ColorInput;
+    /** A single thin horizontal rule under the header row and along the foot of the table (e.g. a
+     *  light-grey separator). Independent of `cellBorder`, which draws the full grid. */
+    rule?: ColorInput;
+}
+/**
+ * A `Column` of `Row`s. Fixed-point columns sit in a fixed-width `Box`, `"Nfr"` fractions
+ * become `Expanded`, so columns align across rows. Being a Column of atomic Rows, it
+ * paginates at row boundaries for free (a row that doesn't fit moves whole). `"auto"`
+ * columns are resolved at layout time (a `DeferredElement`), once metrics are available.
+ */
+export declare function Table(opts: TableOptions, rows: Cell[][]): PDFElement;

package/dist/api/table.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Table = Table;
+const box_constraints_1 = require("../layout/box-constraints");
+const repeating_header_element_1 = require("../elements/layout/repeating-header-element");
+const deferred_element_1 = require("../elements/layout/deferred-element");
+const layout_1 = require("./layout");
+const text_1 = require("./text");
+function asElement(c) {
+    return typeof c === "string" ? (0, text_1.Text)(c) : c;
+}
+/** `"2fr"` → 2, `"fr"` → 1; not a fraction → null. */
+function fractionOf(col) {
+    if (typeof col !== "string" || !col.endsWith("fr"))
+        return null;
+    const n = parseFloat(col);
+    return Number.isFinite(n) ? n : 1;
+}
+/** The cell's unbounded (max-content) width - what an `"auto"` column sizes to. */
+function naturalWidth(cell, cellPadding, ctx) {
+    const el = cellPadding !== undefined ? (0, layout_1.Padding)(cellPadding, asElement(cell)) : asElement(cell);
+    return el.calculateLayout(box_constraints_1.BoxConstraints.loose(Infinity, Infinity), { x: 0, y: 0 }, ctx).width;
+}
+/** Replaces every `"auto"` column with the widest cell width measured down that column. */
+function resolveAutoColumns(opts, rows, ctx) {
+    // The composed cell sits in a 1pt-border Box (border-box) that eats 1pt each side, which the
+    // measured content doesn't include; add it back, and `ceil` so a single-word cell can't land
+    // a hair over the width and wrap to an empty first line.
+    const slack = opts.cellBorder !== undefined || opts.rule !== undefined ? 2 : 0;
+    return opts.columns.map((col, i) => {
+        if (col !== "auto")
+            return col;
+        let w = opts.header ? naturalWidth(opts.header[i], opts.cellPadding, ctx) : 0;
+        for (const r of rows) {
+            if (r[i] !== undefined)
+                w = Math.max(w, naturalWidth(r[i], opts.cellPadding, ctx));
+        }
+        return Math.ceil(w + slack);
+    });
+}
+/** Builds the table tree for already-resolved column widths (no `"auto"`). */
+function composeTable(opts, rows, columns) {
+    var _a, _b, _c, _d;
+    const { cellPadding } = opts;
+    const colGap = (_b = (_a = opts.colGap) !== null && _a !== void 0 ? _a : opts.gap) !== null && _b !== void 0 ? _b : 0;
+    const rowGap = (_d = (_c = opts.rowGap) !== null && _c !== void 0 ? _c : opts.gap) !== null && _d !== void 0 ? _d : 0;
+    const cb = opts.cellBorder;
+    const rule = opts.rule;
+    // The complete grid, once: every cell bottom+right, first row also top, first col also left.
+    const borderFor = (firstRow, firstCol) => cb === undefined
+        ? {}
+        : Object.assign(Object.assign({ borderBottom: cb, borderRight: cb }, (firstRow ? { borderTop: cb } : {})), (firstCol ? { borderLeft: cb } : {}));
+    // `ruled` rows get just a bottom line (the header underline / the table foot), without the full grid.
+    const wrap = (cell, col, firstRow, firstCol, ruled) => {
+        const inner = cellPadding !== undefined ? (0, layout_1.Padding)(cellPadding, asElement(cell)) : asElement(cell);
+        // The border lives on the wrapper, which stretches to the row height (crisp lines).
+        const border = Object.assign(Object.assign({}, borderFor(firstRow, firstCol)), (ruled && rule !== undefined ? { borderBottom: rule } : {}));
+        const boxed = cb !== undefined || (ruled && rule !== undefined);
+        if (typeof col === "number")
+            return (0, layout_1.Box)(Object.assign({ width: col }, border), [inner]);
+        const fr = fractionOf(col);
+        if (fr !== null)
+            return (0, layout_1.Expanded)({ flex: fr }, boxed ? (0, layout_1.Box)(Object.assign({}, border), [inner]) : inner);
+        throw new Error(`Unsupported column width "${col}" - use a number of points or "<n>fr"`);
+    };
+    // align:stretch → equal-height cells, so a wrapping cell keeps the row's bottom rule straight.
+    const buildRow = (cells, firstRow, ruled = false) => (0, layout_1.Row)({ gap: colGap, align: "stretch" }, cells.map((cell, i) => { var _a; return wrap(cell, (_a = columns[i]) !== null && _a !== void 0 ? _a : "1fr", firstRow, i === 0, ruled); }));
+    // The first row (which gets the top border) is the header if present, else body row 0.
+    // `rule` underlines the header and the last body row (the table foot).
+    const last = rows.length - 1;
+    const body = (0, layout_1.Column)({ gap: rowGap }, rows.map((cells, idx) => buildRow(cells, !opts.header && idx === 0, rule !== undefined && idx === last)));
+    return opts.header
+        ? new repeating_header_element_1.RepeatingHeaderElement(buildRow(opts.header, true, rule !== undefined), body, rowGap)
+        : body;
+}
+/**
+ * A `Column` of `Row`s. Fixed-point columns sit in a fixed-width `Box`, `"Nfr"` fractions
+ * become `Expanded`, so columns align across rows. Being a Column of atomic Rows, it
+ * paginates at row boundaries for free (a row that doesn't fit moves whole). `"auto"`
+ * columns are resolved at layout time (a `DeferredElement`), once metrics are available.
+ */
+function Table(opts, rows) {
+    if (opts.columns.some((c) => c === "auto")) {
+        return new deferred_element_1.DeferredElement((ctx) => composeTable(opts, rows, resolveAutoColumns(opts, rows, ctx)));
+    }
+    return composeTable(opts, rows, opts.columns);
+}

package/dist/api/text.d.ts

@@ -0,0 +1,28 @@
+import { TextElement, TextSegment } from "../elements/text-element";
+import { ColorInput } from "./color";
+/** Text styling shared by `Text`, `Paragraph` and `span`. `bold`/`italic` are booleans
+ *  (locked §7.3) and combine into one engine `FontStyle`. */
+export interface TextStyle {
+    size?: number;
+    font?: string;
+    bold?: boolean;
+    italic?: boolean;
+    color?: ColorInput;
+}
+export interface TextOptions extends TextStyle {
+    /** Text-internal alignment (left/center/right) - independent of a parent's `cross` (§5). */
+    align?: "left" | "center" | "right";
+}
+/**
+ * An inline run for mixed-style `Text` (`Text([span("a", {bold:true}), span("b")])`). Each
+ * field overrides the enclosing `Text`'s defaults for just this run; omitted fields inherit.
+ */
+export declare function span(text: string, style?: TextStyle): TextSegment;
+/**
+ * Text. `content` is a plain string or a list of `span(...)` runs for mixed styling. The
+ * options set the defaults (size/font/style/color) that any spans inherit, plus the
+ * text-internal `align`.
+ */
+export declare function Text(content: string | TextSegment[], opts?: TextOptions): TextElement;
+/** `Text` with body-paragraph defaults (same options; a separate name reads as intent). */
+export declare function Paragraph(content: string | TextSegment[], opts?: TextOptions): TextElement;

package/dist/api/text.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.span = span;
+exports.Text = Text;
+exports.Paragraph = Paragraph;
+const text_element_1 = require("../elements/text-element");
+const pdf_element_1 = require("../elements/pdf-element");
+const pdf_object_manager_1 = require("../utils/pdf-object-manager");
+const color_1 = require("./color");
+/** Body-text default size when none is given (matches the engine default font). */
+const DEFAULT_SIZE = 12;
+/** bold + italic → the single engine `FontStyle`. */
+function toFontStyle(bold, italic) {
+    if (bold && italic)
+        return pdf_object_manager_1.FontStyle.BoldItalic;
+    if (bold)
+        return pdf_object_manager_1.FontStyle.Bold;
+    if (italic)
+        return pdf_object_manager_1.FontStyle.Italic;
+    return pdf_object_manager_1.FontStyle.Normal;
+}
+const ALIGN = {
+    left: pdf_element_1.HorizontalAlignment.left,
+    center: pdf_element_1.HorizontalAlignment.center,
+    right: pdf_element_1.HorizontalAlignment.right,
+};
+/**
+ * An inline run for mixed-style `Text` (`Text([span("a", {bold:true}), span("b")])`). Each
+ * field overrides the enclosing `Text`'s defaults for just this run; omitted fields inherit.
+ */
+function span(text, style = {}) {
+    return {
+        content: text,
+        fontSize: style.size,
+        fontFamily: style.font,
+        fontStyle: style.bold !== undefined || style.italic !== undefined
+            ? toFontStyle(style.bold, style.italic)
+            : undefined,
+        fontColor: style.color !== undefined ? (0, color_1.toColor)(style.color) : undefined,
+    };
+}
+/**
+ * Text. `content` is a plain string or a list of `span(...)` runs for mixed styling. The
+ * options set the defaults (size/font/style/color) that any spans inherit, plus the
+ * text-internal `align`.
+ */
+function Text(content, opts = {}) {
+    var _a;
+    return new text_element_1.TextElement({
+        content,
+        fontSize: (_a = opts.size) !== null && _a !== void 0 ? _a : DEFAULT_SIZE,
+        fontFamily: opts.font,
+        fontStyle: toFontStyle(opts.bold, opts.italic),
+        color: opts.color !== undefined ? (0, color_1.toColor)(opts.color) : undefined,
+        textAlignment: opts.align ? ALIGN[opts.align] : undefined,
+    });
+}
+/** `Text` with body-paragraph defaults (same options; a separate name reads as intent). */
+function Paragraph(content, opts = {}) {
+    return Text(content, opts);
+}