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

package/dist/edit/writer.js

@@ -0,0 +1,283 @@
+import { isDict, isRef, isStream, isString, stringsIn, } from "./objects.js";
+/**
+ * Writing changes back into an existing PDF, as an **incremental update**.
+ *
+ * The original bytes are never rewritten. Changed objects are APPENDED, followed by a fresh
+ * cross-reference section whose `/Prev` points back at the old one. That is what the format was designed
+ * for, and it buys three things: we never have to understand (let alone re-emit) the parts of a foreign
+ * file we did not come for; an existing signature over the original bytes stays intact; and the result
+ * carries a property worth testing - **the original file is a literal PREFIX of the output**.
+ */
+const enc = (s) => new TextEncoder().encode(s);
+/**
+ * A PDF string, written back byte-faithfully.
+ *
+ * Only printable ASCII goes into a `(literal)`. Anything else becomes a `<hex>` string, which carries
+ * the SAME bytes but survives the UTF-8 encoder this file is finally written through - a literal holding
+ * byte 0xE4 would otherwise leave as the two bytes 0xC3 0xA4 and read back as mojibake.
+ */
+const stringToken = (b) => {
+    const printable = b.every((byte) => byte >= 0x20 && byte <= 0x7e);
+    if (!printable) {
+        return `<${Array.from(b, (byte) => byte.toString(16).padStart(2, "0").toUpperCase()).join("")}>`;
+    }
+    let out = "";
+    for (const byte of b) {
+        if (byte === 0x28 || byte === 0x29 || byte === 0x5c)
+            out += "\\" + String.fromCharCode(byte);
+        else
+            out += String.fromCharCode(byte);
+    }
+    return `(${out})`;
+};
+/** Escape a PDF name: everything outside the regular characters becomes `#XX`. */
+const escNameToken = (s) => Array.from(enc(s))
+    .map((b) => b >= 0x21 && b <= 0x7e && !"()<>[]{}/%#".includes(String.fromCharCode(b))
+    ? String.fromCharCode(b)
+    : "#" + b.toString(16).padStart(2, "0").toUpperCase())
+    .join("");
+const num = (n) => (Number.isInteger(n) ? String(n) : String(Number(n.toFixed(6))));
+/**
+ * Serialise an object back to PDF syntax. Used only for objects we deliberately change - everything we
+ * do not touch stays in the original bytes, untouched and unre-encoded.
+ *
+ * A string keeps the spelling it was read with: a name written as `<FEFF…>` stays hex, because that is
+ * how the producer encodes unicode and rewriting it as a literal would corrupt it.
+ */
+export function serialize(o, cipher) {
+    if (o === undefined || o === null)
+        return "null";
+    if (typeof o === "number")
+        return num(o);
+    if (typeof o === "boolean")
+        return String(o);
+    if (Array.isArray(o))
+        return `[${o.map((e) => serialize(e, cipher)).join(" ")}]`;
+    if (isRef(o))
+        return `${o.num} ${o.gen} R`;
+    if (isString(o)) {
+        // In an encrypted document every string was deciphered on open, so it is PLAINTEXT here. Writing it
+        // back as-is would leak it; the caller pre-enciphers each one and passes the result in.
+        const enciphered = cipher?.get(o);
+        if (enciphered !== undefined)
+            return enciphered;
+        // A string the producer wrote as hex stays hex; the rest is decided by its bytes.
+        return o.hex
+            ? `<${Array.from(o.bytes, (b) => b.toString(16).padStart(2, "0").toUpperCase()).join("")}>`
+            : stringToken(o.bytes);
+    }
+    if (isStream(o))
+        return `${serialize(o.dict, cipher)}\nstream\n<<stream data>>\nendstream`;
+    if (isDict(o)) {
+        const parts = [];
+        for (const [k, v] of o.map)
+            parts.push(`/${escNameToken(k)} ${serialize(v, cipher)}`);
+        return `<< ${parts.join(" ")} >>`;
+    }
+    return `/${escNameToken(o.name)}`;
+}
+export class IncrementalWriter {
+    constructor(doc) {
+        this.doc = doc;
+        /** Object number -> its new body, in PDF syntax. */
+        this.changed = new Map();
+        /** Numbers this writer invented, as opposed to ones it replaces - they have no recorded generation. */
+        this.added = new Set();
+        // New objects continue after the highest number the file already uses.
+        this.nextNum = Math.max(0, ...doc.objectNumbers()) + 1;
+    }
+    /** Replace an existing object. */
+    update(objNum, body) {
+        this.changed.set(objNum, body);
+    }
+    /** Append a new object and return its number. */
+    add(body) {
+        const n = this.nextNum++;
+        this.added.add(n);
+        this.changed.set(n, body);
+        return n;
+    }
+    /** A shared Helvetica for regenerated appearances, added once and only when one is drawn. */
+    helv() {
+        return (this.helvNum ?? (this.helvNum = this.add("<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>")));
+    }
+    /** The generation to write for an object: the file's own for one we replace, 0 for one we add. */
+    generationOf(objNum) {
+        return this.added.has(objNum) ? 0 : this.doc.generationOf(objNum);
+    }
+    get hasChanges() {
+        return this.changed.size > 0;
+    }
+    /**
+     * Produce the updated file: the original bytes, then every changed object, then a new cross-reference
+     * section chained to the old one.
+     */
+    save() {
+        if (this.changed.size === 0)
+            return this.doc.bytes;
+        const original = this.doc.bytes;
+        const chunks = [original];
+        let offset = original.length;
+        // A file that does not end in a newline would run its last line into our first object.
+        if (original[original.length - 1] !== 10 && original[original.length - 1] !== 13) {
+            chunks.push(enc("\n"));
+            offset += 1;
+        }
+        const offsets = new Map();
+        for (const [objNum, body] of [...this.changed].sort((a, b) => a[0] - b[0])) {
+            offsets.set(objNum, offset);
+            // The generation has to match what the file records, or the new entry describes a different
+            // object than the one being replaced. Objects we ADD are new numbers, and those start at 0.
+            const head = enc(`${objNum} ${this.generationOf(objNum)} obj\n`);
+            chunks.push(head);
+            offset += head.length;
+            if (typeof body === "string") {
+                const b = enc(`${body}\nendobj\n`);
+                chunks.push(b);
+                offset += b.length;
+            }
+            else {
+                const open = enc(`<< ${body.dict} /Length ${body.data.length} >>\nstream\n`);
+                const close = enc(`\nendstream\nendobj\n`);
+                chunks.push(open, body.data, close);
+                offset += open.length + body.data.length + close.length;
+            }
+        }
+        const xrefOffset = offset;
+        chunks.push(this.xrefSection(offsets, xrefOffset));
+        let total = 0;
+        for (const c of chunks)
+            total += c.length;
+        const out = new Uint8Array(total);
+        let at = 0;
+        for (const c of chunks) {
+            out.set(c, at);
+            at += c.length;
+        }
+        return out;
+    }
+    /**
+     * The new cross-reference section, as BYTES.
+     *
+     * Bytes, not a string: an xref stream is binary, and running it through a UTF-8 encoder would turn
+     * every value above 127 into two bytes - which is most offsets, so the whole index becomes garbage.
+     *
+     * A classic table is written when the file already had one; an xref-STREAM file gets a stream,
+     * because mixing the two leaves readers that follow only one kind unable to walk the chain back.
+     */
+    xrefSection(offsets, xrefOffset) {
+        const prev = this.previousStartXref();
+        const rootRef = this.doc.trailer.map.get("Root");
+        const idRef = this.doc.trailer.map.get("ID");
+        const infoRef = this.doc.trailer.map.get("Info");
+        // /Encrypt MUST be carried over. Dropping it declares the file plaintext while its contents are
+        // still ciphertext, so every reader - including ours - hands back raw bytes as field names.
+        const encryptRef = this.doc.trailer.map.get("Encrypt");
+        // An xref stream is itself an object and has to appear in its own index, so its number is taken
+        // first and its offset is where this whole section begins.
+        const all = new Map(offsets);
+        let selfNum;
+        if (this.doc.usesXrefStream) {
+            selfNum = this.nextNum++;
+            all.set(selfNum, xrefOffset);
+        }
+        const size = Math.max(this.nextNum, ...all.keys()) + 1;
+        // Group consecutive object numbers into subsections, which is what both formats want.
+        const nums = [...all.keys()].sort((a, b) => a - b);
+        const runs = [];
+        for (const n of nums) {
+            const last = runs[runs.length - 1];
+            if (last && n === last[0] + last[1].length)
+                last[1].push(n);
+            else
+                runs.push([n, [n]]);
+        }
+        const entry = (key, ref) => ref === undefined ? "" : `${key} ${serialize(ref)}`;
+        if (selfNum !== undefined) {
+            // Rows of `/W [1 4 2]`: in-use marker, 4-byte offset, 2-byte generation. Left uncompressed - a
+            // filter is optional, and a readable appended section is worth more here than a few hundred bytes.
+            const rows = new Uint8Array(nums.length * 7);
+            nums.forEach((n, i) => {
+                const off = all.get(n);
+                const g = n === selfNum ? 0 : this.generationOf(n);
+                rows.set([
+                    1,
+                    (off >>> 24) & 0xff,
+                    (off >>> 16) & 0xff,
+                    (off >>> 8) & 0xff,
+                    off & 0xff,
+                    (g >>> 8) & 0xff,
+                    g & 0xff,
+                ], i * 7);
+            });
+            const index = runs.map(([start, group]) => `${start} ${group.length}`).join(" ");
+            const dict = [
+                "/Type /XRef",
+                `/Size ${size}`,
+                `/Index [${index}]`,
+                "/W [1 4 2]",
+                entry("/Root", rootRef),
+                entry("/Info", infoRef),
+                entry("/ID", idRef),
+                entry("/Encrypt", encryptRef),
+                prev !== undefined ? `/Prev ${prev}` : "",
+                `/Length ${rows.length}`,
+            ].filter(Boolean);
+            const head = enc(`${selfNum} 0 obj\n<< ${dict.join(" ")} >>\nstream\n`);
+            const tail = enc(`\nendstream\nendobj\nstartxref\n${xrefOffset}\n%%EOF\n`);
+            const out = new Uint8Array(head.length + rows.length + tail.length);
+            out.set(head, 0);
+            out.set(rows, head.length);
+            out.set(tail, head.length + rows.length);
+            return out;
+        }
+        let table = "xref\n";
+        for (const [start, group] of runs) {
+            table += `${start} ${group.length}\n`;
+            for (const n of group) {
+                const g = String(this.generationOf(n)).padStart(5, "0");
+                table += `${String(all.get(n)).padStart(10, "0")} ${g} n \n`;
+            }
+        }
+        const trailer = [
+            `/Size ${size}`,
+            entry("/Root", rootRef),
+            entry("/Info", infoRef),
+            entry("/ID", idRef),
+            entry("/Encrypt", encryptRef),
+            prev !== undefined ? `/Prev ${prev}` : "",
+        ].filter(Boolean);
+        return enc(`${table}trailer\n<< ${trailer.join(" ")} >>\nstartxref\n${xrefOffset}\n%%EOF\n`);
+    }
+    /** The offset the ORIGINAL file's `startxref` pointed at - our `/Prev`. */
+    previousStartXref() {
+        const tail = new TextDecoder("latin1").decode(this.doc.bytes.subarray(Math.max(0, this.doc.bytes.length - 2048)));
+        const at = tail.lastIndexOf("startxref");
+        if (at < 0)
+            return undefined;
+        const m = /startxref\s+(\d+)/.exec(tail.slice(at));
+        return m ? Number(m[1]) : undefined;
+    }
+}
+/** Bytes as an enciphered PDF hex string, the form every rewritten string takes in an encrypted file. */
+const hexString = (b) => `<${Array.from(b, (x) => x.toString(16).padStart(2, "0").toUpperCase()).join("")}>`;
+/**
+ * Encipher every string the given objects carry, into the cipher map `serialize` consults.
+ *
+ * Not optional on an encrypted document: `serialize` writes any string missing from the map as
+ * PLAINTEXT, so an object rewritten without this pass leaks whatever it holds.
+ */
+export async function carryStrings(doc, objects, into = new Map()) {
+    if (!doc.isEncrypted)
+        return into;
+    for (const o of objects) {
+        for (const str of stringsIn(o)) {
+            if (into.has(str))
+                continue;
+            const cipher = await doc.encryptForWrite(str.bytes);
+            if (cipher)
+                into.set(str, hexString(cipher));
+        }
+    }
+    return into;
+}

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

@@ -9,9 +9,26 @@ interface ContainerElementParams extends SizedElement, WithChildren {
     main?: MainAlign;
     /** Horizontal alignment of each child (cross axis); defaults to `stretch`. */
     cross?: CrossAlign;
+    /** Lay the children out backwards along the main axis (CSS `row-reverse`). */
+    reverse?: boolean;
+    /** Let the children flow onto further lines when they do not fit (CSS `flex-wrap`). */
+    wrap?: boolean;
+    /** How the block of wrapped lines sits across the axis (CSS `align-content`). */
+    alignContent?: MainAlign;
     /** Width/height as a fraction (0..1) of the offered box instead of `width`/`height` (relative sizing). */
     widthFactor?: number;
     heightFactor?: number;
+    /** Lower / upper bounds per axis, in points or as a fraction; see `SizingParams`. */
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    minWidthFactor?: number;
+    maxWidthFactor?: number;
+    minHeightFactor?: number;
+    maxHeightFactor?: number;
+    /** width / height; derives whichever axis is left open (CSS `aspect-ratio`). */
+    aspectRatio?: number;
     /** Start this stack on a fresh page (CSS `break-before: page`). */
     breakBefore?: boolean;
     /** Start everything after this stack on a fresh page (CSS `break-after: page`). */
@@ -22,10 +39,13 @@ export declare class ContainerElement extends SizedPDFElement implements Fragmen
     private gap;
     private main;
     private cross;
+    private reverse;
+    private wrap;
+    private alignContent?;
     private breakBefore;
     private breakAfter;
     private requested;
-    constructor({ x, y, width, height, children, gap, main, cross, widthFactor, heightFactor, breakBefore, breakAfter, }: ContainerElementParams);
+    constructor({ x, y, width, height, children, gap, main, cross, reverse, wrap, alignContent, breakBefore, breakAfter, ...sizing }: ContainerElementParams);
     breaksBefore(): boolean;
     breaksAfter(): boolean;
     /**

package/dist/elements/container-element.js

@@ -1,15 +1,18 @@
 import { FlexLayoutHelper, VERTICAL_AXIS } from "../utils/flex-layout.js";
-import { resolveExtent } from "../layout/box-constraints.js";
+import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
 import { childrenForceBreak, packChildren, } from "../layout/fragmentation.js";
 import { FlexiblePDFElement, SizedPDFElement, } from "./pdf-element.js";
 export class ContainerElement extends SizedPDFElement {
-    constructor({ x, y, width, height, children, gap, main, cross, widthFactor, heightFactor, breakBefore, breakAfter, }) {
+    constructor({ x, y, width, height, children, gap, main, cross, reverse, wrap, alignContent, breakBefore, breakAfter, ...sizing }) {
         super({ x, y, width, height });
         this.children = children;
         this.gap = gap ?? 0;
         this.main = main ?? "start";
         this.cross = cross ?? "stretch";
-        this.requested = { width, height, widthFactor, heightFactor };
+        this.reverse = reverse ?? false;
+        this.wrap = wrap ?? false;
+        this.alignContent = alignContent;
+        this.requested = { ...sizing, width, height };
         this.breakBefore = breakBefore ?? false;
         this.breakAfter = breakAfter ?? false;
     }
@@ -62,6 +65,9 @@ export class ContainerElement extends SizedPDFElement {
             gap: this.gap,
             main: this.main,
             cross: this.cross,
+            reverse: this.reverse,
+            wrap: this.wrap,
+            alignContent: this.alignContent,
             breakAfter,
         });
     }
@@ -93,17 +99,19 @@ export class ContainerElement extends SizedPDFElement {
         // Relative sizing: a pinned extent (fixed points or a fraction of the offered box, clamped into
         // the constraints) wins; else fill a bounded axis; else stay `undefined` and shrink-wrap below.
         // A Column nested in a Row gets unbounded width - passing 0 there would collapse children to 0.
-        const explicitWidth = resolveExtent(this.requested.width, this.requested.widthFactor, constraints.maxWidth, constraints.hasBoundedWidth);
-        const explicitHeight = resolveExtent(this.requested.height, this.requested.heightFactor, constraints.maxHeight, constraints.hasBoundedHeight);
+        const specs = extentSpecs(this.requested);
+        const resolved = resolveSize(specs.width, specs.height, this.requested.aspectRatio, constraints);
+        const { width: explicitWidth, height: explicitHeight, constraints: bounds } = resolved;
+        // Fill-or-shrink-wrap is decided by the constraints we were GIVEN; a min/max only caps the result.
         const boundedWidth = explicitWidth !== undefined
-            ? constraints.constrainWidth(explicitWidth)
+            ? bounds.constrainWidth(explicitWidth)
             : constraints.hasBoundedWidth
-                ? constraints.maxWidth
+                ? bounds.maxWidth
                 : undefined;
         const boundedHeight = explicitHeight !== undefined
-            ? constraints.constrainHeight(explicitHeight)
+            ? bounds.constrainHeight(explicitHeight)
             : constraints.hasBoundedHeight
-                ? constraints.maxHeight
+                ? bounds.maxHeight
                 : undefined;
         // Vertical stack: cross = width (children fill it), main = height (the stacking extent).
         const crossAvail = boundedWidth ?? Infinity;
@@ -113,7 +121,14 @@ export class ContainerElement extends SizedPDFElement {
             // Vertical flex stack (main = height, cross = width). The shared helper measures
             // fixed children, distributes the leftover to flex children, and places everything
             // in source order.
-            result = FlexLayoutHelper.layout(this.children, VERTICAL_AXIS, mainAvail, crossAvail, this.y, this.x, { gap: this.gap, main: this.main, cross: this.cross }, ctx);
+            result = FlexLayoutHelper.layout(this.children, VERTICAL_AXIS, mainAvail, crossAvail, this.y, this.x, {
+                gap: this.gap,
+                main: this.main,
+                cross: this.cross,
+                reverse: this.reverse,
+                wrap: this.wrap,
+                alignContent: this.alignContent,
+            }, ctx);
         }
         // Pinned/bounded axis takes that extent; an unbounded one shrink-wraps to the children (height =
         // the stack, width = the widest child). Top-left coordinates; the container draws nothing, and

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

@@ -0,0 +1,51 @@
+import { Color } from "../../common/color.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "../pdf-element.js";
+import type { CheckboxSpec, FieldStyle } from "../../forms/field.js";
+export interface CheckboxParams {
+    /** The field name (/T) - unique in the document. */
+    name: string;
+    /** Whether it starts checked. */
+    checked?: boolean;
+    /** The "on" export value (default `"Yes"`). */
+    onValue?: string;
+    /** Tooltip / accessible name. */
+    tooltip?: string;
+    /** Show but do not allow toggling. */
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before submitting. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). */
+    print?: boolean;
+    /** Box side length in points (default 14). */
+    size?: number;
+    /** Checkmark colour (default black). */
+    color?: Color;
+    /** Box border colour (default a mid grey, so the box is visible). */
+    border?: Color;
+    /** Box background fill. */
+    background?: Color;
+    /** Border thickness (default 1). */
+    borderWidth?: number;
+}
+/**
+ * A checkbox (AcroForm /Btn). A small square leaf that draws nothing itself: it reserves its box and
+ * emits a `formfield` IR node whose checkbox spec bakes an /AP checkmark at the seam.
+ */
+export declare class CheckboxElement extends SizedPDFElement {
+    private spec;
+    private style;
+    private size;
+    constructor(p: CheckboxParams);
+    calculateLayout(_constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    getProps(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        spec: CheckboxSpec;
+        style: FieldStyle;
+    };
+}

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

@@ -0,0 +1,48 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * A checkbox (AcroForm /Btn). A small square leaf that draws nothing itself: it reserves its box and
+ * emits a `formfield` IR node whose checkbox spec bakes an /AP checkmark at the seam.
+ */
+export class CheckboxElement extends SizedPDFElement {
+    constructor(p) {
+        const size = p.size ?? 14;
+        super({ x: 0, y: 0, width: size, height: size });
+        this.size = size;
+        this.spec = {
+            kind: "checkbox",
+            name: p.name,
+            checked: p.checked,
+            onValue: p.onValue,
+            tooltip: p.tooltip,
+            readOnly: p.readOnly,
+            required: p.required,
+            hidden: p.hidden,
+            print: p.print,
+        };
+        this.style = {
+            border: p.border ?? new Color(102, 102, 102),
+            background: p.background,
+            color: p.color ?? new Color(0, 0, 0),
+            fontSize: 0,
+            borderWidth: p.borderWidth ?? 1,
+        };
+    }
+    calculateLayout(_constraints, offset, _ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = this.size;
+        this.height = this.size;
+        return { width: this.size, height: this.size };
+    }
+    getProps() {
+        return {
+            x: this.x,
+            y: this.y,
+            width: this.width ?? 0,
+            height: this.height ?? 0,
+            spec: this.spec,
+            style: this.style,
+        };
+    }
+}

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

@@ -0,0 +1,53 @@
+import { Color } from "../../common/color.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "../pdf-element.js";
+import type { ChoiceOption, ChoiceSpec, FieldAlign, FieldStyle } from "../../forms/field.js";
+export interface ChoiceParams {
+    name: string;
+    options: ChoiceOption[];
+    /** `true` = dropdown (combo box), `false` = list box. */
+    combo: boolean;
+    editable?: boolean;
+    multiSelect?: boolean;
+    value?: string;
+    values?: string[];
+    tooltip?: string;
+    readOnly?: boolean;
+    /** How the value sits in the box (default left). */
+    align?: FieldAlign;
+    /** Mark it as a field that must be filled in before submitting. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). */
+    print?: boolean;
+    /** Box width; omit to fill the offered width. */
+    width?: number;
+    /** Box height; omit for a single-line default (dropdown) / a few rows (list box). */
+    height?: number;
+    fontSize?: number;
+    color?: Color;
+    border?: Color;
+    background?: Color;
+    borderWidth?: number;
+}
+/**
+ * A choice field (AcroForm /Ch) - a dropdown or a list box, chosen by `combo`. A leaf that draws nothing
+ * itself: it reserves its box and emits a `formfield` IR node. The selected value is rendered by the
+ * viewer via /NeedAppearances (Step 1); Step 4 bakes its /AP.
+ */
+export declare class ChoiceElement extends SizedPDFElement {
+    private spec;
+    private style;
+    private requested;
+    constructor(p: ChoiceParams);
+    calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    getProps(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        spec: ChoiceSpec;
+        style: FieldStyle;
+    };
+}

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

@@ -0,0 +1,59 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * A choice field (AcroForm /Ch) - a dropdown or a list box, chosen by `combo`. A leaf that draws nothing
+ * itself: it reserves its box and emits a `formfield` IR node. The selected value is rendered by the
+ * viewer via /NeedAppearances (Step 1); Step 4 bakes its /AP.
+ */
+export class ChoiceElement extends SizedPDFElement {
+    constructor(p) {
+        super({ x: 0, y: 0, width: p.width, height: p.height });
+        const fontSize = p.fontSize ?? 12;
+        this.spec = {
+            kind: "choice",
+            name: p.name,
+            options: p.options,
+            combo: p.combo,
+            editable: p.editable,
+            multiSelect: p.multiSelect,
+            value: p.value,
+            values: p.values,
+            tooltip: p.tooltip,
+            readOnly: p.readOnly,
+            align: p.align,
+            required: p.required,
+            hidden: p.hidden,
+            print: p.print,
+        };
+        this.style = {
+            border: p.border ?? new Color(154, 164, 178),
+            background: p.background,
+            color: p.color ?? new Color(0, 0, 0),
+            fontSize,
+            borderWidth: p.borderWidth ?? 1,
+        };
+        this.requested = { width: p.width, height: p.height, fontSize, combo: p.combo };
+    }
+    calculateLayout(constraints, offset, _ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = this.requested.width ?? (constraints.hasBoundedWidth ? constraints.maxWidth : 200);
+        // Dropdown: one line. List box: a few rows tall so several options are visible.
+        const oneLine = this.requested.fontSize + 9;
+        const rows = Math.max(3, Math.min(this.spec.options.length, 5));
+        this.height =
+            this.requested.height ??
+                (this.requested.combo ? oneLine : rows * (this.requested.fontSize + 4));
+        return { width: this.width, height: this.height };
+    }
+    getProps() {
+        return {
+            x: this.x,
+            y: this.y,
+            width: this.width ?? 0,
+            height: this.height ?? 0,
+            spec: this.spec,
+            style: this.style,
+        };
+    }
+}

package/dist/elements/forms/push-button-element.d.ts

@@ -0,0 +1,56 @@
+import { Color } from "../../common/color.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "../pdf-element.js";
+import type { ButtonAction, FieldStyle, PushButtonSpec } from "../../forms/field.js";
+export interface PushButtonParams {
+    /** The field name (/T) - unique in the document. */
+    name: string;
+    /** The caption drawn on the button. */
+    label: string;
+    /** What clicking it does; omit for a button that does nothing. */
+    action?: ButtonAction;
+    /** Tooltip / accessible name. */
+    tooltip?: string;
+    /** Draw it but do not let it be clicked. */
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before submitting. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). */
+    print?: boolean;
+    /** Button width in points; omit to fill the offered width. */
+    width?: number;
+    /** Button height in points; omit for a comfortable default. */
+    height?: number;
+    /** Caption font size (default 12). */
+    fontSize?: number;
+    /** Caption colour (default black). */
+    color?: Color;
+    /** Border colour (default a mid grey). */
+    border?: Color;
+    /** Button face fill (default a light grey, so it reads as a button). */
+    background?: Color;
+    /** Border thickness (default 1). */
+    borderWidth?: number;
+}
+/**
+ * A push button (AcroForm /Btn, Pushbutton flag). Holds no value - it fires an action. Draws nothing
+ * itself: it reserves its box and emits a `formfield` IR node whose caption is baked into an /AP at the
+ * seam, so the button looks identical in every viewer and in print.
+ */
+export declare class PushButtonElement extends SizedPDFElement {
+    private spec;
+    private style;
+    private requested;
+    constructor(p: PushButtonParams);
+    calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    getProps(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        spec: PushButtonSpec;
+        style: FieldStyle;
+    };
+}