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

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;
+    };
+}

package/dist/elements/forms/push-button-element.js

@@ -0,0 +1,49 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * 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 class PushButtonElement extends SizedPDFElement {
+    constructor(p) {
+        super({ x: 0, y: 0, width: p.width, height: p.height });
+        const fontSize = p.fontSize ?? 12;
+        this.spec = {
+            kind: "pushbutton",
+            name: p.name,
+            label: p.label,
+            action: p.action,
+            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 ?? new Color(238, 240, 245),
+            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;
+        this.width = this.requested.width ?? (constraints.hasBoundedWidth ? constraints.maxWidth : 120);
+        this.height = this.requested.height ?? this.requested.fontSize + 14;
+        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/radio-element.d.ts

@@ -0,0 +1,52 @@
+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, RadioSpec } from "../../forms/field.js";
+export interface RadioParams {
+    /** The shared group name - radios with the same `group` are one mutually-exclusive field. */
+    group: string;
+    /** This button's export value - unique within the group. */
+    value: string;
+    /** Whether this button starts selected (at most one per group should be). */
+    selected?: boolean;
+    /** Tooltip / accessible name. */
+    tooltip?: string;
+    /** Show but do not allow changing the group. */
+    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 diameter in points (default 14). */
+    size?: number;
+    /** Dot colour (default black). */
+    color?: Color;
+    /** Ring colour (default a mid grey). */
+    border?: Color;
+    /** Fill behind the ring. */
+    background?: Color;
+    /** Ring thickness (default 1). */
+    borderWidth?: number;
+}
+/**
+ * One radio button (AcroForm /Btn, Radio flag). A small round leaf; several sharing a `group` become one
+ * mutually-exclusive field (see `RadioGroup` for the ergonomic wrapper). Draws nothing itself - it emits a
+ * `formfield` IR node whose radio spec bakes the ring + dot /AP at the seam.
+ */
+export declare class RadioElement extends SizedPDFElement {
+    private spec;
+    private style;
+    private size;
+    constructor(p: RadioParams);
+    calculateLayout(_constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    getProps(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        spec: RadioSpec;
+        style: FieldStyle;
+    };
+}

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

@@ -0,0 +1,49 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * One radio button (AcroForm /Btn, Radio flag). A small round leaf; several sharing a `group` become one
+ * mutually-exclusive field (see `RadioGroup` for the ergonomic wrapper). Draws nothing itself - it emits a
+ * `formfield` IR node whose radio spec bakes the ring + dot /AP at the seam.
+ */
+export class RadioElement extends SizedPDFElement {
+    constructor(p) {
+        const size = p.size ?? 14;
+        super({ x: 0, y: 0, width: size, height: size });
+        this.size = size;
+        this.spec = {
+            kind: "radio",
+            group: p.group,
+            value: p.value,
+            selected: p.selected,
+            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/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/image-element.d.ts

@@ -1,5 +1,6 @@
-import { BoxConstraints, Offset, Size } from "../layout/box-constraints";
-import { LayoutContext, SizedPDFElement } from "./pdf-element";
+import type { Radii } from "../ir/display-list.js";
+import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "./pdf-element.js";
 export declare enum BoxFit {
     none = "NONE",
     contain = "CONTAIN",
@@ -19,6 +20,7 @@ export declare class CustomLocalImage extends CustomImage {
     private imagePath;
     private fileBuffer;
     private fileRawData;
+    private dims?;
     constructor(imagePath: string);
     init(): Promise<void>;
     getImageType(): Promise<string>;
@@ -29,19 +31,68 @@ export declare class CustomLocalImage extends CustomImage {
         height: number;
     }>;
 }
+/**
+ * An image straight from raw bytes (a browser upload / fetch, no filesystem). The PDF filter is sniffed
+ * from the magic bytes: JPEG embeds raw (DCTDecode, no decode step), PNG is decoded to RGB (FlateDecode).
+ */
+export declare class CustomBytesImage extends CustomImage {
+    private bytes;
+    private fileRawData;
+    private dims?;
+    constructor(bytes: Uint8Array);
+    init(): Promise<void>;
+    getImageType(): Promise<string>;
+    getFileData(): string;
+    getImageDimensions(): Promise<{
+        width: number;
+        height: number;
+    }>;
+}
 interface ImageElementParams {
     image: CustomImage;
     width?: number;
     height?: number;
+    /** Width as a fraction (0..1) of the offered width instead of a fixed `width` (relative sizing). */
+    widthFactor?: number;
+    /** Height as a fraction (0..1) of the offered height; see `widthFactor`. */
+    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; overrides the image's OWN ratio (CSS `aspect-ratio`), `fit` then places it. */
+    aspectRatio?: number;
     fit?: BoxFit;
-    /** Corner radius in points; rounds the image box (0 = sharp, default). */
-    radius?: number;
+    /** Corner radius in points - one number or per corner; rounds the image box (0 = sharp, default). */
+    radius?: number | Radii;
+    /** Alternate text for accessibility (tagged PDF). With `alt` the image is a Figure; without, decoration. */
+    alt?: string;
 }
 export declare class ImageElement extends SizedPDFElement {
     private image;
+    private widthFactor?;
+    private heightFactor?;
     private fit;
     private radius;
-    constructor({ image, width, height, fit, radius }: ImageElementParams);
+    private readonly alt?;
+    private requested;
+    /** min/max/aspectRatio, kept as given so every layout pass re-resolves them. */
+    private sizing;
+    private intrinsic?;
+    constructor({ image, width, height, widthFactor, heightFactor, fit, radius, alt, ...sizing }: ImageElementParams);
+    /**
+     * Loads the image and records its intrinsic pixel size. Runs in the async pre-layout pass (layout
+     * itself is synchronous and cannot await jimp) so `calculateLayout` can turn a width-only image
+     * into a proportional box. Best-effort: a load failure leaves the size unresolved (the renderer
+     * surfaces the real error) and the image just keeps whatever explicit size it was given.
+     */
+    resolveIntrinsicSize(): Promise<void>;
+    relativeSizeFactor(horizontal: boolean): number | undefined;
     calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
     getProps(): {
         x: number;
@@ -50,7 +101,8 @@ export declare class ImageElement extends SizedPDFElement {
         height: number | undefined;
         image: CustomImage;
         fit: BoxFit;
-        radius: number;
+        radius: number | Radii;
+        alt: string | undefined;
     };
 }
 export {};