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

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

@@ -0,0 +1,54 @@
+import { Color } from "../../common/color.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "../pdf-element.js";
+import type { FieldStyle, SignatureSpec } from "../../forms/field.js";
+export interface SignatureFieldParams {
+    /** The field name (/T) - unique in the document. */
+    name: string;
+    /** A hint drawn inside the empty box, e.g. "Signature". */
+    label?: string;
+    /** Tooltip / accessible name. */
+    tooltip?: string;
+    /** Draw it but do not let it be signed. */
+    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 width in points; omit to fill the offered width. */
+    width?: number;
+    /** Box height in points (default 48 - room for a signature). */
+    height?: number;
+    /** Hint font size (default 9). */
+    fontSize?: number;
+    /** Hint colour (default a muted grey). */
+    color?: Color;
+    /** Box border + signing-rule colour (default a mid grey). */
+    border?: Color;
+    /** Box background fill. */
+    background?: Color;
+    /** Border thickness (default 1). */
+    borderWidth?: number;
+}
+/**
+ * A signature field (AcroForm /Sig) - a PLACEHOLDER someone can sign later. jasy creates the field and
+ * its empty "sign here" appearance; it does not sign (that needs a certificate and a byte-range digest -
+ * a separate feature). Draws nothing itself: it reserves its box and emits a `formfield` IR node.
+ */
+export declare class SignatureFieldElement extends SizedPDFElement {
+    private spec;
+    private style;
+    private requested;
+    constructor(p: SignatureFieldParams);
+    calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    getProps(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        spec: SignatureSpec;
+        style: FieldStyle;
+    };
+}

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

@@ -0,0 +1,47 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * A signature field (AcroForm /Sig) - a PLACEHOLDER someone can sign later. jasy creates the field and
+ * its empty "sign here" appearance; it does not sign (that needs a certificate and a byte-range digest -
+ * a separate feature). Draws nothing itself: it reserves its box and emits a `formfield` IR node.
+ */
+export class SignatureFieldElement extends SizedPDFElement {
+    constructor(p) {
+        super({ x: 0, y: 0, width: p.width, height: p.height });
+        this.spec = {
+            kind: "signature",
+            name: p.name,
+            label: p.label,
+            tooltip: p.tooltip,
+            readOnly: p.readOnly,
+            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(107, 114, 128),
+            fontSize: p.fontSize ?? 9,
+            borderWidth: p.borderWidth ?? 1,
+        };
+        this.requested = { width: p.width, height: p.height };
+    }
+    calculateLayout(constraints, offset, _ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = this.requested.width ?? (constraints.hasBoundedWidth ? constraints.maxWidth : 240);
+        this.height = this.requested.height ?? 48;
+        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/text-field-element.d.ts

@@ -0,0 +1,61 @@
+import { Color } from "../../common/color.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "../pdf-element.js";
+import type { FieldAlign, FieldStyle, TextFieldSpec } from "../../forms/field.js";
+export interface TextFieldParams {
+    /** The field name (/T) - unique in the document; you read the value back by it. */
+    name: string;
+    /** Initial value (/V). */
+    value?: string;
+    /** Tooltip / accessible name (/TU). */
+    tooltip?: string;
+    /** Wrap across lines instead of one line. */
+    multiline?: boolean;
+    /** Mask the input. */
+    password?: boolean;
+    /** Maximum character count. */
+    maxLength?: number;
+    /** Show but do not allow editing. */
+    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 in points; omit to fill the offered width. */
+    width?: number;
+    /** Box height in points; omit for a single-line default (`multiline` wants an explicit height). */
+    height?: number;
+    /** Value font size; `0` = viewer auto-size. */
+    fontSize?: number;
+    /** Value text colour. */
+    color?: Color;
+    /** Box border colour (omit for no border). */
+    border?: Color;
+    /** Box background fill (omit for transparent). */
+    background?: Color;
+    /** Border thickness in points. */
+    borderWidth?: number;
+}
+/**
+ * A text input field (AcroForm /Tx). A leaf that draws NOTHING itself: it reserves its box in the layout
+ * and emits a `formfield` IR node that becomes a Widget annotation + /AcroForm field at the seam.
+ */
+export declare class TextFieldElement extends SizedPDFElement {
+    private spec;
+    private style;
+    private requested;
+    constructor(p: TextFieldParams);
+    calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    getProps(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        spec: TextFieldSpec;
+        style: FieldStyle;
+    };
+}

package/dist/elements/forms/text-field-element.js

@@ -0,0 +1,54 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * A text input field (AcroForm /Tx). A leaf that draws NOTHING itself: it reserves its box in the layout
+ * and emits a `formfield` IR node that becomes a Widget annotation + /AcroForm field at the seam.
+ */
+export class TextFieldElement extends SizedPDFElement {
+    constructor(p) {
+        super({ x: 0, y: 0, width: p.width, height: p.height });
+        const fontSize = p.fontSize ?? 12;
+        this.spec = {
+            kind: "text",
+            name: p.name,
+            value: p.value,
+            tooltip: p.tooltip,
+            multiline: p.multiline,
+            password: p.password,
+            maxLength: p.maxLength,
+            readOnly: p.readOnly,
+            align: p.align,
+            required: p.required,
+            hidden: p.hidden,
+            print: p.print,
+        };
+        this.style = {
+            border: p.border,
+            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 };
+    }
+    calculateLayout(constraints, offset, _ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        // Width: explicit, else fill the offered box (a form field with no width spans the column).
+        this.width = this.requested.width ?? (constraints.hasBoundedWidth ? constraints.maxWidth : 200);
+        // Height: explicit, else a comfortable single line (font size + padding). Multiline without an
+        // explicit height still gets the single-line default - the caller should size a multiline box.
+        this.height = this.requested.height ?? this.requested.fontSize + 9;
+        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/index.d.ts

@@ -8,6 +8,12 @@ export * from "./layout/expanded-element.js";
 export * from "./layout/padding-element.js";
 export * from "./layout/page-break-element.js";
 export * from "./layout/keep-together-element.js";
+export * from "./forms/text-field-element.js";
+export * from "./forms/checkbox-element.js";
+export * from "./forms/radio-element.js";
+export * from "./forms/choice-element.js";
+export * from "./forms/push-button-element.js";
+export * from "./forms/signature-element.js";
 export * from "./layout/default-text-style-element.js";
 export * from "./layout/positioned-element.js";
 export * from "./layout/link-element.js";

package/dist/elements/index.js

@@ -8,6 +8,12 @@ export * from "./layout/expanded-element.js";
 export * from "./layout/padding-element.js";
 export * from "./layout/page-break-element.js";
 export * from "./layout/keep-together-element.js";
+export * from "./forms/text-field-element.js";
+export * from "./forms/checkbox-element.js";
+export * from "./forms/radio-element.js";
+export * from "./forms/choice-element.js";
+export * from "./forms/push-button-element.js";
+export * from "./forms/signature-element.js";
 export * from "./layout/default-text-style-element.js";
 export * from "./layout/positioned-element.js";
 export * from "./layout/link-element.js";

package/dist/forms/acroform.d.ts

@@ -0,0 +1,63 @@
+import type { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import type { FormFieldNode } from "../ir/display-list.js";
+/**
+ * Collects the document's form fields as pages render, then emits the catalog `/AcroForm` dictionary at
+ * finalize. Mirrors `OutlineBuilder` / `DestRegistry`: a no-op returning "" when no field was placed, so
+ * a document without a form stays byte-identical.
+ */
+export declare class AcroFormCollector {
+    private fieldRefs;
+    private radioGroups;
+    private needAppearances;
+    private helvNum?;
+    private zadbNum?;
+    private hasSignature;
+    private usedNames;
+    private bake;
+    /** Turn appearance baking off (`renderToBytes(doc, { fieldAppearances: false })`). */
+    setBakeAppearances(on: boolean): void;
+    /** The size to draw a value at. A field may ask for `0` - the PDF convention for "auto-size"; we then
+     *  fit the capitals comfortably inside the box, which is what a viewer's auto-size does. */
+    private drawSize;
+    /** Measure one line for the appearance generator. */
+    private line;
+    /** Bake a text field's value into an appearance stream; returns the XObject number. */
+    private bakeText;
+    /** Bake a choice field: a combo shows its current value on one line, a list box shows its options
+     *  with the selected rows highlighted. */
+    private bakeChoice;
+    get isEmpty(): boolean;
+    private helv;
+    /**
+     * ZapfDingbats, the font a check mark lives in. Needed even though we bake the appearance ourselves:
+     * a viewer told to regenerate (`/NeedAppearances`, which filling a form sets) redraws a check box from
+     * its `/DA`, and the conventional `/DA` for one names `/ZaDb`. Without the matching `/DR` entry the
+     * viewer cannot resolve the font - poppler says "Unknown font tag 'ZaDb'" and draws no check at all.
+     * No encoding: ZapfDingbats brings its own.
+     */
+    private zadb;
+    /**
+     * A field name is its identity: two fields sharing one are ONE field to every viewer, showing the same
+     * value in both places and overwriting each other as the reader types. The format allows it and says
+     * nothing, so the mistake surfaces only when someone fills the form. Named here instead.
+     *
+     * A radio GROUP is the exception - its buttons deliberately share a name, which is what makes them
+     * mutually exclusive - so it never comes through here.
+     */
+    private claimName;
+    /** Emit the widget object for one form-field IR node, register it as a field, and return its object
+     *  number so the PageRenderer can add it to that page's /Annots. */
+    addField(node: FormFieldNode, om: PDFObjectManager): number;
+    /** A push button (/Btn, Pushbutton flag): no value, an optional action, and a baked caption. The
+     *  caption is measured here (the appearance module stays free of font metrics) and drawn into an
+     *  appearance stream that carries its own font resource. */
+    private buildPushButtonWidget;
+    /** A radio button: one KID widget of its group's shared field. The group field is reserved on first
+     *  sight (and added to /Fields); each button adds itself to that field's /Kids. Returns the kid widget
+     *  number, which goes into the PAGE /Annots (the parent field does not). */
+    private addRadio;
+    /** A signature field (/Sig): an EMPTY placeholder with a baked "sign here" face. No /V - an unsigned
+     *  field has no value; a signing tool fills that in (and replaces this appearance) later. */
+    private buildSignatureWidget;
+    finalize(om: PDFObjectManager): string;
+}