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

package/dist/api/dimension.d.ts

@@ -0,0 +1,76 @@
+import type { Radii } from "../ir/display-list.js";
+import type { CrossAlign } from "../layout/alignment.js";
+/**
+ * Size input for a Box's `width` / `height` (relative sizing). Either a number of PDF points (a
+ * fixed size) or a percentage string like `"50%"` - a fraction of the space the parent offers on
+ * that axis. Every form normalizes to a `Dimension` via `toDimension`, so the engine only ever sees
+ * points and factors, never a string. A percentage resolves against the parent's offered extent, so
+ * it only has meaning inside a bounded region (a fraction of an unbounded axis is a no-op).
+ */
+export type SizeInput = number | `${number}%`;
+/** A resolved `SizeInput`: exactly one of an absolute point size or a 0..1 fraction of the parent. */
+export interface Dimension {
+    /** Absolute size in PDF points. */
+    points?: number;
+    /** Fraction of the parent's offered extent on this axis; a `"50%"` input is `0.5`. */
+    factor?: number;
+}
+/**
+ * Normalizes a `SizeInput` to a `Dimension` (a point size or a fraction). Rejects negatives at this
+ * boundary so `resolveExtent` and the layout never see a negative size.
+ */
+export declare function toDimension(value: SizeInput): Dimension;
+/** The bound and ratio options every sized factory accepts, in the public `SizeInput` form. */
+export interface BoundsInput {
+    /**
+     * This element's own cross-axis alignment inside its Column / Row (CSS `align-self`), overriding the
+     * container's `align`. On a `Spacer` / `Expanded` it is a no-op - a flex child fills the main axis and
+     * has no natural cross size to align.
+     */
+    alignSelf?: CrossAlign;
+    /**
+     * Where this child sits among its siblings (CSS `order`), lowest first, source order deciding ties.
+     * It moves the child in the LAYOUT only - the element tree is untouched, so a tagged PDF still
+     * exposes the source reading order. Default 0.
+     */
+    order?: number;
+    /**
+     * How willingly this child gives up main-axis space when the line overflows (CSS `flex-shrink`),
+     * weighted by its own size. **Default 0, deliberately unlike CSS's 1** - shrinking changes what a
+     * document looks like, so it is opted into per child rather than applied to everything at once.
+     */
+    flexShrink?: number;
+    minWidth?: SizeInput;
+    maxWidth?: SizeInput;
+    minHeight?: SizeInput;
+    maxHeight?: SizeInput;
+    /**
+     * width / height (CSS `aspect-ratio`). Fills in whichever axis you leave open, and sizes the box
+     * from the offered width when you leave both open. An explicit `min`/`max` still wins over it.
+     */
+    aspectRatio?: number;
+}
+/** Split `BoundsInput` into the points-and-factors form the elements take. */
+export declare function toBounds(o: BoundsInput): {
+    minWidth: number | undefined;
+    maxWidth: number | undefined;
+    minHeight: number | undefined;
+    maxHeight: number | undefined;
+    minWidthFactor: number | undefined;
+    maxWidthFactor: number | undefined;
+    minHeightFactor: number | undefined;
+    maxHeightFactor: number | undefined;
+    aspectRatio: number | undefined;
+};
+/**
+ * Corner radius input. A single number rounds all four corners; the object names them; the tuple is
+ * CSS order - `[topLeft, topRight, bottomRight, bottomLeft]`, clockwise from the top left.
+ */
+export type RadiusInput = number | {
+    topLeft?: number;
+    topRight?: number;
+    bottomRight?: number;
+    bottomLeft?: number;
+} | [number, number, number, number];
+/** Normalizes a `RadiusInput` to the engine's short corner names. */
+export declare function toRadius(r: RadiusInput): number | Radii;

package/dist/api/dimension.js

@@ -0,0 +1,43 @@
+const PERCENT = /^(\d+(?:\.\d+)?)%$/; // no leading "-": a size cannot be negative
+/**
+ * Normalizes a `SizeInput` to a `Dimension` (a point size or a fraction). Rejects negatives at this
+ * boundary so `resolveExtent` and the layout never see a negative size.
+ */
+export function toDimension(value) {
+    if (typeof value === "number") {
+        if (value < 0)
+            throw new Error(`Invalid size ${value}: a size cannot be negative.`);
+        return { points: value };
+    }
+    const m = PERCENT.exec(value.trim());
+    if (m)
+        return { factor: parseFloat(m[1]) / 100 };
+    throw new Error(`Invalid size "${value}": use a number of points or a percentage like "50%".`);
+}
+/** Split `BoundsInput` into the points-and-factors form the elements take. */
+export function toBounds(o) {
+    const d = (v) => (v !== undefined ? toDimension(v) : undefined);
+    const [minW, maxW, minH, maxH] = [d(o.minWidth), d(o.maxWidth), d(o.minHeight), d(o.maxHeight)];
+    if (o.aspectRatio !== undefined && !(o.aspectRatio > 0)) {
+        throw new Error(`Invalid aspectRatio ${o.aspectRatio}: it is width / height and must be above 0.`);
+    }
+    return {
+        minWidth: minW?.points,
+        maxWidth: maxW?.points,
+        minHeight: minH?.points,
+        maxHeight: maxH?.points,
+        minWidthFactor: minW?.factor,
+        maxWidthFactor: maxW?.factor,
+        minHeightFactor: minH?.factor,
+        maxHeightFactor: maxH?.factor,
+        aspectRatio: o.aspectRatio,
+    };
+}
+/** Normalizes a `RadiusInput` to the engine's short corner names. */
+export function toRadius(r) {
+    if (typeof r === "number")
+        return r;
+    if (Array.isArray(r))
+        return { tl: r[0], tr: r[1], br: r[2], bl: r[3] };
+    return { tl: r.topLeft, tr: r.topRight, br: r.bottomRight, bl: r.bottomLeft };
+}

package/dist/api/font-url.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Loading a font over the network for `doc.addFontFromUrl(...)`.
+ *
+ * `addFont` resolves its source AT REGISTRATION - a path is read there and then - and this keeps the
+ * same contract, differing only in being async. So the failure lands where you asked for the font,
+ * not somewhere inside a later render.
+ *
+ * `fetch` is used directly: it is in every browser and in Node since 18, so this needs no platform
+ * port, unlike the filesystem read beside it.
+ */
+/** One font file by URL, or a styled family of them. Mirrors `FontSource`, with strings meaning URLs. */
+export type UrlFontSource = string | {
+    normal: string;
+    bold?: string;
+    italic?: string;
+    boldItalic?: string;
+};
+/** Thrown when a font could not be fetched or is not one we can parse. Always says which URL. */
+export declare class FontUrlError extends Error {
+    constructor(message: string);
+}
+/** Fetch a whole `UrlFontSource`, in parallel for a family. */
+export declare function loadFontFromUrl(source: UrlFontSource): Promise<Uint8Array | {
+    normal: Uint8Array;
+    bold?: Uint8Array;
+    italic?: Uint8Array;
+    boldItalic?: Uint8Array;
+}>;

package/dist/api/font-url.js

@@ -0,0 +1,134 @@
+/**
+ * Loading a font over the network for `doc.addFontFromUrl(...)`.
+ *
+ * `addFont` resolves its source AT REGISTRATION - a path is read there and then - and this keeps the
+ * same contract, differing only in being async. So the failure lands where you asked for the font,
+ * not somewhere inside a later render.
+ *
+ * `fetch` is used directly: it is in every browser and in Node since 18, so this needs no platform
+ * port, unlike the filesystem read beside it.
+ */
+/** Thrown when a font could not be fetched or is not one we can parse. Always says which URL. */
+export class FontUrlError extends Error {
+    constructor(message) {
+        super(`@jasy/pdf: ${message}`);
+    }
+}
+/**
+ * What the first four bytes of an sfnt file say it is. Checked here because `TTFParser` does not look
+ * at them: it goes straight for the table directory, so an HTML error page or a WOFF would fail deep
+ * inside with `missing required table "head"` instead of saying what the file actually is.
+ */
+function describeSignature(bytes) {
+    const tag = String.fromCharCode(...bytes.subarray(0, 4));
+    const v = (bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3];
+    if (v === 0x00010000 || tag === "true")
+        return { ok: true, what: "TrueType" };
+    if (tag === "OTTO")
+        return { ok: false, what: "an OpenType/CFF font, which jasy does not parse yet" };
+    if (tag === "wOFF")
+        return { ok: true, what: "WOFF" };
+    if (tag === "wOF2")
+        return { ok: false, what: "a WOFF2 font, which jasy does not parse yet" };
+    if (tag === "ttcf")
+        return { ok: false, what: "a TrueType Collection, which jasy does not parse yet" };
+    if (tag.startsWith("<") || tag === "%PDF")
+        return { ok: false, what: "not a font at all" };
+    return { ok: false, what: "not a font we recognise" };
+}
+/** How long one font may take to arrive before we give up. A hung server must not hang a render. */
+const TIMEOUT_MS = 15000;
+/**
+ * How large a font file may be. Generous on purpose - a full CJK face is tens of megabytes and is a
+ * legitimate thing to embed - but not unbounded: a URL pointing at the wrong file (a video, a disk
+ * image) would otherwise be read into memory in full before anyone notices it is not a font.
+ */
+const MAX_BYTES = 32 * 1024 * 1024;
+/** Read the body with a running ceiling, so an oversized response is dropped WHILE it arrives. */
+async function readBounded(response, url) {
+    // `Content-Length` is the cheap early exit; a server may omit or misstate it, so it is a hint only
+    // and the real ceiling is enforced below while reading.
+    const declared = Number(response.headers?.get?.("content-length") ?? NaN);
+    if (Number.isFinite(declared) && declared > MAX_BYTES) {
+        throw new FontUrlError(`the font at ${url} is ${declared} bytes; the limit is ${MAX_BYTES}`);
+    }
+    const body = response.body;
+    if (!body?.getReader) {
+        // No streaming body (an older runtime, or a stubbed response): fall back to reading it whole and
+        // checking afterwards. Weaker, but never worse than not checking at all.
+        const whole = new Uint8Array(await response.arrayBuffer());
+        if (whole.length > MAX_BYTES) {
+            throw new FontUrlError(`the font at ${url} is larger than the ${MAX_BYTES} byte limit`);
+        }
+        return whole;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.length;
+        if (total > MAX_BYTES) {
+            await reader.cancel();
+            throw new FontUrlError(`the font at ${url} is larger than the ${MAX_BYTES} byte limit`);
+        }
+        chunks.push(value);
+    }
+    if (chunks.length === 1)
+        return chunks[0];
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const c of chunks) {
+        out.set(c, at);
+        at += c.length;
+    }
+    return out;
+}
+/** Fetch one font file and hand back its bytes, refusing anything we could not embed. */
+async function fetchFont(url) {
+    let response;
+    try {
+        response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    }
+    catch (e) {
+        const why = e?.name === "TimeoutError" || e?.name === "AbortError"
+            ? `it did not respond within ${TIMEOUT_MS} ms`
+            : String(e?.message ?? e);
+        throw new FontUrlError(`could not fetch the font at ${url}: ${why}`);
+    }
+    if (!response.ok) {
+        throw new FontUrlError(`the font at ${url} could not be fetched: HTTP ${response.status}`);
+    }
+    // Everything past here still talks to the network, so a failure mid-body must not escape as a raw
+    // TypeError - a caller catching FontUrlError would miss it.
+    let bytes;
+    try {
+        bytes = await readBounded(response, url);
+    }
+    catch (e) {
+        if (e instanceof FontUrlError)
+            throw e;
+        throw new FontUrlError(`the font at ${url} could not be read: ${String(e?.message ?? e)}`);
+    }
+    if (bytes.length < 4) {
+        throw new FontUrlError(`the font at ${url} is empty`);
+    }
+    const { ok, what } = describeSignature(bytes);
+    if (!ok) {
+        throw new FontUrlError(`the file at ${url} is ${what}. jasy embeds TrueType-flavoured fonts (.ttf and .woff)`);
+    }
+    return bytes;
+}
+/** Fetch a whole `UrlFontSource`, in parallel for a family. */
+export async function loadFontFromUrl(source) {
+    if (typeof source === "string")
+        return fetchFont(source);
+    const styles = ["normal", "bold", "italic", "boldItalic"];
+    const wanted = styles.filter((s) => source[s] !== undefined);
+    const loaded = await Promise.all(wanted.map((s) => fetchFont(source[s])));
+    const family = { normal: new Uint8Array() };
+    wanted.forEach((s, i) => (family[s] = loaded[i]));
+    return family;
+}

package/dist/api/forms.d.ts

@@ -0,0 +1,347 @@
+import { PDFElement } from "../elements/pdf-element.js";
+import { TextFieldElement } from "../elements/forms/text-field-element.js";
+import { RadioElement } from "../elements/forms/radio-element.js";
+import { ChoiceElement } from "../elements/forms/choice-element.js";
+import { PushButtonElement } from "../elements/forms/push-button-element.js";
+import { SignatureFieldElement } from "../elements/forms/signature-element.js";
+import type { FieldAlign } from "../forms/field.js";
+import { ColorInput } from "./color.js";
+/** A choice option: a plain string (value = label) or `{ value, label }`. */
+export type ChoiceOptionInput = string | {
+    value: string;
+    label?: string;
+};
+/** Options for a `TextField` - an interactive text input in the generated PDF. */
+export interface TextFieldOptions {
+    /** The field name - unique in the document; you read the value back by it. */
+    name: string;
+    /** Initial value. */
+    value?: string;
+    /** Tooltip / accessible name shown on hover. */
+    tooltip?: string;
+    /** Accept multiple lines instead of one (give the box a `height` to match). */
+    multiline?: boolean;
+    /** Mask the typed characters (a password field). */
+    password?: boolean;
+    /** How the value sits in the box: left (default), center or right. */
+    align?: FieldAlign;
+    /** Maximum number of characters. */
+    maxLength?: number;
+    /** Show the value but do not let the user edit it. */
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before the form is submitted. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). `false` keeps it on screen only. */
+    print?: boolean;
+    /** Box width in points; omit to fill the offered width. */
+    width?: number;
+    /** Box height in points; omit for a single-line default. */
+    height?: number;
+    /** Value font size in points; `0` lets the viewer auto-size. */
+    fontSize?: number;
+    /** Value text colour (named / hex / rgb). */
+    color?: ColorInput;
+    /** Box border colour; omit for no border. */
+    border?: ColorInput;
+    /** Box background fill; omit for transparent. */
+    background?: ColorInput;
+    /** Border thickness in points (default 1 when a border is set). */
+    borderWidth?: number;
+}
+/**
+ * An interactive text field the reader of the PDF can type into (AcroForm /Tx). Place it like any element -
+ * in a `Column`, `Row`, `Box` or a table cell; it reserves its box and becomes a fillable widget.
+ *
+ * ```ts
+ * TextField({ name: "email", border: "gray", height: 22 })
+ * ```
+ */
+export declare function TextField(opts: TextFieldOptions): TextFieldElement;
+/** Options for a `Checkbox` - a toggle the reader of the PDF can tick. */
+export interface CheckboxOptions {
+    /** The field name - unique in the document. */
+    name: string;
+    /** Text placed beside the box. Given one, the box and the text become a row - the same shape
+     *  `RadioGroup` builds for its choices, so a lone check box does not have to be assembled by hand. */
+    label?: string;
+    /** Size of the label text (default 12). */
+    labelSize?: number;
+    /** Colour of the label text. */
+    labelColor?: ColorInput;
+    /** Space between the box and its label, in points (default 8). */
+    labelGap?: number;
+    /** Whether it starts checked. */
+    checked?: boolean;
+    /** The "on" export value stored when checked (default `"Yes"`). */
+    onValue?: string;
+    /** Tooltip / accessible name shown on hover. */
+    tooltip?: string;
+    /** Show the state but do not let the user toggle it. */
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before the form is submitted. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). `false` keeps it on screen only. */
+    print?: boolean;
+    /** Box side length in points (default 14). */
+    size?: number;
+    /** Checkmark colour (default black). */
+    color?: ColorInput;
+    /** Box border colour (default a mid grey). */
+    border?: ColorInput;
+    /** Box background fill. */
+    background?: ColorInput;
+    /** Border thickness in points (default 1). */
+    borderWidth?: number;
+}
+/**
+ * An interactive checkbox (AcroForm /Btn). It bakes its own checkmark appearance, so the tick shows in
+ * any viewer, in print, and under PDF/A - not only in ones that regenerate appearances.
+ *
+ * ```ts
+ * Row({ gap: 6, align: "center" }, [Checkbox({ name: "agree" }), Text("I agree")])
+ * ```
+ */
+export declare function Checkbox(opts: CheckboxOptions): PDFElement;
+/** Options for a single `Radio` button. Several sharing a `group` are one mutually-exclusive field. */
+export interface RadioOptions {
+    /** The shared group name - radios with the same `group` are one field. */
+    group: string;
+    /** This button's export value - unique within the group. */
+    value: string;
+    /** Whether it starts selected. */
+    selected?: boolean;
+    /** Tooltip / accessible name. */
+    tooltip?: string;
+    /** Show but do not allow changing. */
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before the form is submitted. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). `false` keeps it on screen only. */
+    print?: boolean;
+    /** Button diameter in points (default 14). */
+    size?: number;
+    /** Dot colour. */
+    color?: ColorInput;
+    /** Ring colour. */
+    border?: ColorInput;
+    /** Fill behind the ring. */
+    background?: ColorInput;
+    /** Ring thickness. */
+    borderWidth?: number;
+}
+/** A single radio button. Use `RadioGroup` for the common labelled-list layout, or this for custom ones. */
+export declare function Radio(opts: RadioOptions): RadioElement;
+/** One option in a `RadioGroup`. */
+export interface RadioChoice {
+    /** The export value stored when this option is picked. */
+    value: string;
+    /** The text shown next to the button. */
+    label: string;
+}
+/** Options for a `RadioGroup` - the labelled list of mutually-exclusive buttons. */
+export interface RadioGroupOptions {
+    /** The field name (shared by every button). */
+    name: string;
+    /** Mark the group as required. */
+    required?: boolean;
+    /** Hide every button - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the buttons when printing (default true). */
+    print?: boolean;
+    /** The value of the option that starts selected (matches one option's `value`). */
+    value?: string;
+    /** Vertical space between options (default 8). */
+    gap?: number;
+    /** Button diameter (default 14). */
+    size?: number;
+    /** Button ring / dot / background colours, applied to every option. */
+    color?: ColorInput;
+    border?: ColorInput;
+    background?: ColorInput;
+    /** Label font size (default 12) and colour. */
+    labelSize?: number;
+    labelColor?: ColorInput;
+}
+/**
+ * A labelled group of mutually-exclusive radio buttons. Sugar over `Radio` + `Text`: it lays each option
+ * out as a button-and-label row in a `Column`, and marks the one whose `value` matches the group `value`.
+ *
+ * ```ts
+ * RadioGroup({ name: "size", value: "m" }, [
+ *   { value: "s", label: "Small" },
+ *   { value: "m", label: "Medium" },
+ *   { value: "l", label: "Large" },
+ * ])
+ * ```
+ */
+export declare function RadioGroup(opts: RadioGroupOptions, options: RadioChoice[]): PDFElement;
+/** Style + geometry shared by `Dropdown` and `ListBox`. */
+interface ChoiceStyleOptions {
+    /** How the value sits in the box: left (default), center or right. */
+    align?: FieldAlign;
+    tooltip?: string;
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before the form is submitted. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). `false` keeps it on screen only. */
+    print?: boolean;
+    width?: number;
+    height?: number;
+    fontSize?: number;
+    color?: ColorInput;
+    border?: ColorInput;
+    background?: ColorInput;
+    borderWidth?: number;
+}
+/** Options for a `Dropdown` (combo box). */
+export interface DropdownOptions extends ChoiceStyleOptions {
+    /** The field name. */
+    name: string;
+    /** The selected value. */
+    value?: string;
+    /** Let the reader type a value that is not in the list. */
+    editable?: boolean;
+}
+/**
+ * A dropdown / combo box (AcroForm /Ch). Options are plain strings or `{ value, label }`.
+ *
+ * ```ts
+ * Dropdown({ name: "country", value: "de" }, [{ value: "de", label: "Germany" }, "France"])
+ * ```
+ */
+export declare function Dropdown(opts: DropdownOptions, options: ChoiceOptionInput[]): ChoiceElement;
+/** `Select` is an alias for `Dropdown`. */
+export declare const Select: typeof Dropdown;
+/** Options for a `ListBox`. */
+export interface ListBoxOptions extends ChoiceStyleOptions {
+    /** The field name. */
+    name: string;
+    /** The selected value (single-select). */
+    value?: string;
+    /** The selected values (when `multiSelect`). */
+    values?: string[];
+    /** Allow more than one selection. */
+    multiSelect?: boolean;
+}
+/**
+ * A scrollable list box (AcroForm /Ch). Give it a `height` to show more rows. Set `multiSelect` for
+ * several selections at once.
+ */
+export declare function ListBox(opts: ListBoxOptions, options: ChoiceOptionInput[]): ChoiceElement;
+/**
+ * What a `PushButton` does when clicked: `"reset"` clears the form, `{ submit: url }` posts the field
+ * values, `{ open: url }` opens a link. Omit it for a button that does nothing. Scripted (JavaScript)
+ * actions are deliberately not offered - a jasy form is data, not a program.
+ *
+ * VIEWER SUPPORT. All three actions we emit are spec-correct; what differs is what a viewer implements.
+ * PROVEN, not assumed - the same cases built with pdf-lib (an independent producer) behave identically,
+ * so none of this is a jasy bug. Measured 2026-07 in pdf.js (VS Code) and poppler/Evince:
+ *   - `"reset"`         - works in both. The safe one.
+ *   - `{ open: url }`   - works in pdf.js, dead in Evince, and NOT fixable from here: poppler's glib
+ *                         layer surfaces actions only through `poppler_page_get_link_mapping` (i.e.
+ *                         /Link annotations); its form-field API has no action getter at all, so a
+ *                         WIDGET's /A can never be reached. **For a plain hyperlink use `Link({ href })`**
+ *                         - the identical URI action on a real /Link annotation works in both.
+ *   - `{ submit: url }` - Acrobat only. `POPPLER_ACTION_SUBMIT_FORM` does not exist in poppler-glib (no
+ *                         such enum value), and pdf.js does not implement /SubmitForm either.
+ * Ruled out as causes: pdf-lib splits field and widget, sets /P and a /D appearance - and still fails
+ * the same way, so none of those structural differences matter.
+ */
+export type ButtonActionInput = "reset" | {
+    submit: string;
+} | {
+    open: string;
+};
+/** Options for a `PushButton`. */
+export interface PushButtonOptions {
+    /** The field name - unique in the document. */
+    name: string;
+    /** The caption drawn on the button. */
+    label: string;
+    /** What clicking it does. */
+    action?: ButtonActionInput;
+    /** Tooltip / accessible name shown on hover. */
+    tooltip?: string;
+    /** Draw it but do not let it be clicked. */
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before the form is submitted. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). `false` keeps it on screen only. */
+    print?: boolean;
+    /** Width in points; omit to fill the offered width. */
+    width?: number;
+    /** Height in points; omit for a comfortable default. */
+    height?: number;
+    /** Caption font size (default 12). */
+    fontSize?: number;
+    /** Caption colour. */
+    color?: ColorInput;
+    /** Border colour. */
+    border?: ColorInput;
+    /** Button face fill. */
+    background?: ColorInput;
+    /** Border thickness in points. */
+    borderWidth?: number;
+}
+/**
+ * A clickable push button (AcroForm /Btn). It holds no value - it fires an action. Its caption is baked
+ * into the appearance, so the button looks the same in every viewer and in print.
+ *
+ * ```ts
+ * PushButton({ name: "send", label: "Submit", action: { submit: "https://example.com/f" }, width: 120 })
+ * PushButton({ name: "clear", label: "Reset", action: "reset", width: 90 })
+ * ```
+ */
+export declare function PushButton(opts: PushButtonOptions): PushButtonElement;
+/** Options for a `SignatureField`. */
+export interface SignatureFieldOptions {
+    /** The field name - unique in the document. */
+    name: string;
+    /** A hint drawn inside the empty box, e.g. "Signature" or "Approved by". */
+    label?: string;
+    /** Tooltip / accessible name shown on hover. */
+    tooltip?: string;
+    /** Draw it but do not let it be signed. */
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before the form is submitted. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). `false` keeps it on screen only. */
+    print?: boolean;
+    /** Width in points; omit to fill the offered width. */
+    width?: number;
+    /** Height in points (default 48). */
+    height?: number;
+    /** Hint font size (default 9). */
+    fontSize?: number;
+    /** Hint colour. */
+    color?: ColorInput;
+    /** Box border + signing-rule colour. */
+    border?: ColorInput;
+    /** Box background fill. */
+    background?: ColorInput;
+    /** Border thickness in points. */
+    borderWidth?: number;
+}
+/**
+ * A signature field (AcroForm /Sig) - a placeholder someone can sign later in a PDF tool. jasy creates
+ * the field and draws its empty "sign here" box; it does not apply signatures itself (real signing needs
+ * a certificate and a byte-range digest).
+ *
+ * ```ts
+ * SignatureField({ name: "approver", label: "Signature", width: 240 })
+ * ```
+ */
+export declare function SignatureField(opts: SignatureFieldOptions): SignatureFieldElement;
+export {};