pdf-oxide 0.3.37 → 0.3.39

package/lib/builders/document-builder.d.ts

@@ -0,0 +1,350 @@
+/**
+ * Fluent document builder — the programmatic multi-page construction API
+ * exposed through the C FFI.
+ *
+ * Mirrors the Python / WASM / C# / Go equivalents. The same handle-lifetime
+ * contract applies: terminal methods (`build`, `save`, `saveEncrypted`,
+ * `toBytesEncrypted`) CONSUME the builder, and only one `PageBuilder` may
+ * be open at a time.
+ *
+ * @example
+ * ```typescript
+ * import { DocumentBuilder, EmbeddedFont } from 'pdf-oxide';
+ *
+ * const font = EmbeddedFont.fromFile('DejaVuSans.ttf');
+ * const builder = DocumentBuilder.create()
+ *   .title('Hello')
+ *   .registerEmbeddedFont('DejaVu', font);   // consumes `font`
+ * builder.a4Page()
+ *   .font('DejaVu', 12)
+ *   .at(72, 720).text('Привет, мир!')
+ *   .at(72, 700).text('Καλημέρα κόσμε')
+ *   .done();
+ * const bytes = builder.build();            // consumes the builder
+ * ```
+ */
+import { Align, type Column, type SpanCell, type StreamingTableConfig, type TableMode, type TableSpec } from '../types/common.js';
+import { StreamingTable } from './streaming-table.js';
+/**
+ * TTF/OTF font handle registerable with {@link DocumentBuilder}. Single-use:
+ * after `registerEmbeddedFont` the native handle is moved into the builder
+ * and this object becomes disposed.
+ */
+export declare class EmbeddedFont {
+    private _handle;
+    private _consumed;
+    private constructor();
+    /** Load a TTF / OTF font from disk. */
+    static fromFile(path: string): EmbeddedFont;
+    /** Load a font from a byte buffer; pass `name` to override the PostScript name. */
+    static fromBytes(data: Uint8Array | Buffer, name?: string): EmbeddedFont;
+    /** @internal — used by {@link DocumentBuilder.registerEmbeddedFont} */
+    get handle(): unknown;
+    /** @internal — called by the builder after the FFI transfers ownership. */
+    markConsumed(): void;
+    /** Release the native font handle if it hasn't been consumed. */
+    close(): void;
+    /** Symbol.dispose support for `using` declarations. */
+    [Symbol.dispose](): void;
+}
+/**
+ * Fluent top-level API for multi-page PDF construction.
+ * Use {@link DocumentBuilder.create} to start a new builder.
+ */
+export declare class DocumentBuilder {
+    private _handle;
+    private _consumed;
+    private _openPage;
+    private constructor();
+    /** Create a fresh empty builder. */
+    static create(): DocumentBuilder;
+    /** @internal — used by PageBuilder.done */
+    clearOpenPage(): void;
+    private checkUsable;
+    /** Set the document title. */
+    title(title: string): this;
+    /** Set the document author. */
+    author(author: string): this;
+    /** Set the document subject. */
+    subject(subject: string): this;
+    /** Set the document keywords (comma-separated per PDF convention). */
+    keywords(keywords: string): this;
+    /** Set the creator application name. */
+    creator(creator: string): this;
+    /** Run a JavaScript script when the document is opened (/OpenAction). */
+    onOpen(script: string): this;
+    /**
+     * Enable PDF/UA-1 tagged PDF mode.
+     *
+     * When enabled, `build()` emits `/MarkInfo`, `/StructTreeRoot`, `/Lang`, and
+     * `/ViewerPreferences` in the catalog. Opt-in — no effect unless called.
+     * Bundle F-1/F-2.
+     */
+    taggedPdfUa1(): this;
+    /**
+     * Set the document's natural language tag, e.g. `"en-US"`.
+     *
+     * Emitted as `/Lang` in the catalog when `taggedPdfUa1()` is set. Bundle F-2.
+     */
+    language(lang: string): this;
+    /**
+     * Add a role-map entry: custom structure type → standard PDF structure type.
+     *
+     * Emitted in `/RoleMap` inside the StructTreeRoot when `taggedPdfUa1()` is
+     * set. Multiple calls accumulate entries. Bundle F-4.
+     */
+    roleMap(custom: string, standard: string): this;
+    /**
+     * Register a TTF / OTF font under `name`. CONSUMES `font` on success —
+     * do not call `close()` on the font afterwards.
+     */
+    registerEmbeddedFont(name: string, font: EmbeddedFont): this;
+    /** Start a new A4 page. Only one page may be outstanding per builder. */
+    a4Page(): PageBuilder;
+    /** Start a new US Letter page. */
+    letterPage(): PageBuilder;
+    /** Start a page with custom dimensions in PDF points (72 pt = 1 inch). */
+    page(width: number, height: number): PageBuilder;
+    private consumeHandle;
+    /** Build the PDF and return the bytes. CONSUMES the builder. */
+    build(): Buffer;
+    /** Save the PDF to a file. CONSUMES the builder. */
+    save(path: string): void;
+    /** Save the PDF with AES-256 encryption. CONSUMES the builder. */
+    saveEncrypted(path: string, userPassword: string, ownerPassword: string): void;
+    /** Return the PDF as encrypted bytes (AES-256). CONSUMES the builder. */
+    toBytesEncrypted(userPassword: string, ownerPassword: string): Buffer;
+    /** Release native resources if the builder wasn't consumed. */
+    close(): void;
+    /** Symbol.dispose support for `using` declarations. */
+    [Symbol.dispose](): void;
+}
+/**
+ * Fluent per-page builder returned by `DocumentBuilder.a4Page` etc.
+ * Single-use — `done()` commits the page and invalidates this builder.
+ */
+export declare class PageBuilder {
+    private _parent;
+    private _handle;
+    private _done;
+    /** @internal — constructed by DocumentBuilder */
+    constructor(parent: DocumentBuilder, handle: unknown);
+    private h;
+    /** Set font + size for subsequent text. */
+    font(name: string, size: number): this;
+    /** Move the cursor to absolute coordinates. */
+    at(x: number, y: number): this;
+    /** Emit a line of text at the current cursor position. */
+    text(text: string): this;
+    /** Emit a heading (level 1-6). */
+    heading(level: number, text: string): this;
+    /** Emit a paragraph with automatic line wrapping. */
+    paragraph(text: string): this;
+    /** Advance the cursor by the given number of points. */
+    space(points: number): this;
+    /** Draw a horizontal rule across the page. */
+    horizontalRule(): this;
+    /** Attach a URL link to the previous text element. */
+    linkUrl(url: string): this;
+    /** Link the previous text to an internal page (0-based). */
+    linkPage(pageIndex: number): this;
+    /** Link the previous text to a named destination. */
+    linkNamed(destination: string): this;
+    /** Link the previous text to a JavaScript action. */
+    linkJavascript(script: string): this;
+    /** Run JavaScript when this page is opened (/AA /O). */
+    onOpen(script: string): this;
+    /** Run JavaScript when this page is closed (/AA /C). */
+    onClose(script: string): this;
+    /** Set a keystroke JS action (/AA /K) on the last form field. */
+    fieldKeystroke(script: string): this;
+    /** Set a format JS action (/AA /F) on the last form field. */
+    fieldFormat(script: string): this;
+    /** Set a validate JS action (/AA /V) on the last form field. */
+    fieldValidate(script: string): this;
+    /** Set a calculate JS action (/AA /C) on the last form field. */
+    fieldCalculate(script: string): this;
+    /** Highlight the previous text with an RGB colour (channels 0-1). */
+    highlight(r: number, g: number, b: number): this;
+    /** Underline the previous text. */
+    underline(r: number, g: number, b: number): this;
+    /** Strike through the previous text. */
+    strikeout(r: number, g: number, b: number): this;
+    /** Squiggly-underline the previous text. */
+    squiggly(r: number, g: number, b: number): this;
+    /** Attach a sticky-note annotation to the previous text. */
+    stickyNote(text: string): this;
+    /** Place a sticky-note at an absolute position. */
+    stickyNoteAt(x: number, y: number, text: string): this;
+    /** Apply a text watermark to the page. */
+    watermark(text: string): this;
+    /** Apply the standard "CONFIDENTIAL" diagonal watermark. */
+    watermarkConfidential(): this;
+    /** Apply the standard "DRAFT" diagonal watermark. */
+    watermarkDraft(): this;
+    /**
+     * Attach a standard stamp annotation at the cursor (150×50 default).
+     * `typeName` matches the PDF spec's standard stamps (Approved,
+     * NotApproved, Draft, Confidential, Final, Experimental, Expired,
+     * ForPublicRelease, NotForPublicRelease, AsIs, Sold, Departmental,
+     * ForComment, TopSecret) — any other name becomes a custom stamp.
+     */
+    stamp(typeName: string): this;
+    /** Place a free-flowing text annotation inside the rectangle (x, y, w, h). */
+    freeText(x: number, y: number, w: number, h: number, text: string): this;
+    /**
+     * Add a single-line text form field at the rectangle (x, y, w, h).
+     * `name` is the unique field identifier used for form submission;
+     * `defaultValue` is the initial text (pass undefined for blank).
+     */
+    textField(name: string, x: number, y: number, w: number, h: number, defaultValue?: string): this;
+    /**
+     * Add a checkbox form field at the rectangle (x, y, w, h).
+     * `checked` sets the initial state.
+     */
+    checkbox(name: string, x: number, y: number, w: number, h: number, checked?: boolean): this;
+    /**
+     * Add a dropdown combo-box form field. `options` are the user-
+     * visible choices; `selected` picks the initial value.
+     */
+    comboBox(name: string, x: number, y: number, w: number, h: number, options: string[], selected?: string): this;
+    /**
+     * Add a radio-button group. `buttons` is an array of
+     * `[exportValue, x, y, w, h]` tuples — one per option. `selected`
+     * picks the initial value by export value.
+     */
+    radioGroup(name: string, buttons: Array<[string, number, number, number, number]>, selected?: string): this;
+    /** Add a clickable push button with a visible caption. */
+    pushButton(name: string, x: number, y: number, w: number, h: number, caption: string): this;
+    /** Add an unsigned signature placeholder field (/FT /Sig) at the given bounds. */
+    signatureField(name: string, x: number, y: number, w: number, h: number): this;
+    /**
+     * Add a footnote: inline `refMark` emitted at the cursor position, and
+     * `noteText` placed near the page bottom with a separator artifact line.
+     */
+    footnote(refMark: string, noteText: string): this;
+    /**
+     * Lay out `text` as balanced multi-column flow.
+     * `columnCount` columns separated by `gapPt` points.
+     * Paragraphs in `text` are delimited by `"\n\n"`.
+     */
+    columns(columnCount: number, gapPt: number, text: string): this;
+    /**
+     * Emit `text` inline at the current cursor position without advancing
+     * to a new line. The cursor advances horizontally so the next `inline`
+     * call follows on the same line.
+     */
+    inline(text: string): this;
+    /** Emit `text` inline in bold weight. */
+    inlineBold(text: string): this;
+    /** Emit `text` inline in italic style. */
+    inlineItalic(text: string): this;
+    /** Emit `text` inline in an RGB colour (channels 0–1). */
+    inlineColor(r: number, g: number, b: number, text: string): this;
+    /** Advance the cursor to the start of the next line. */
+    newline(): this;
+    /**
+     * Place a 1-D barcode image on the page at `(x, y, w, h)`.
+     * `barcodeType`: 0=Code128 1=Code39 2=EAN13 3=EAN8 4=UPCA 5=ITF
+     * 6=Code93 7=Codabar.
+     */
+    barcode1d(barcodeType: number, data: string, x: number, y: number, w: number, h: number): this;
+    /** Place a QR-code image on the page (square: `size × size` pt). */
+    barcodeQr(data: string, x: number, y: number, size: number): this;
+    /**
+     * Embed an image with an accessibility alt text (PDF/UA-1 §Figure).
+     * `bytes` must contain raw JPEG/PNG/WebP image data.
+     */
+    imageWithAlt(bytes: Buffer | Uint8Array, x: number, y: number, w: number, h: number, altText: string): this;
+    /**
+     * Embed a decorative image as an /Artifact (no alt text, PDF/UA-1 §Artifact).
+     * `bytes` must contain raw JPEG/PNG/WebP image data.
+     */
+    imageArtifact(bytes: Buffer | Uint8Array, x: number, y: number, w: number, h: number): this;
+    /** Draw a stroked rectangle outline (1pt black). */
+    rect(x: number, y: number, w: number, h: number): this;
+    /** Draw a filled rectangle in RGB colour (channels 0–1). */
+    filledRect(x: number, y: number, w: number, h: number, r: number, g: number, b: number): this;
+    /** Draw a line from `(x1, y1)` to `(x2, y2)` with 1pt black stroke. */
+    line(x1: number, y1: number, x2: number, y2: number): this;
+    /**
+     * Draw a stroked rectangle outline with caller-supplied width + RGB
+     * colour (channels 0–1). Underlies the Table surface.
+     */
+    strokeRect(x: number, y: number, w: number, h: number, style?: {
+        width?: number;
+        color?: [number, number, number];
+    }): this;
+    /**
+     * Draw a straight line with caller-supplied width + RGB colour.
+     */
+    strokeLine(x1: number, y1: number, x2: number, y2: number, style?: {
+        width?: number;
+        color?: [number, number, number];
+    }): this;
+    /**
+     * Place wrapped text inside the rectangle (x, y, w, h) with the
+     * given horizontal alignment. Uses the current font + size. Text
+     * that does not fit is clipped to the rectangle height.
+     */
+    textInRect(x: number, y: number, w: number, h: number, text: string, align?: Align): this;
+    /**
+     * Start a new page with the *same* dimensions as the current one.
+     * Text config (font + size) carries over; the cursor resets to the
+     * top-left margin. Callers wanting header-repeat-on-break must
+     * re-emit the header explicitly.
+     */
+    newPageSameSize(): this;
+    /**
+     * Measure the width of `text` in the current font and size.
+     *
+     * Note: v0.3.39 ships a JS-side approximation (0.55em per glyph for
+     * ASCII / typical Latin-1 characters). A true per-glyph measurement
+     * FFI is pending. The result is in PDF points.
+     */
+    measure(text: string): number;
+    /**
+     * Estimate the remaining vertical space on the page at the current
+     * cursor position. v0.3.39 returns `null` when the native cursor is
+     * unknown — callers should treat `null` as "unknown; assume fresh
+     * page". A real FFI hook is pending in a follow-up release.
+     */
+    remainingSpace(): number | null;
+    /**
+     * Emit a buffered table at the current cursor. All rows are
+     * marshalled into a single FFI call — memory scales with the row
+     * count. For million-row streams use {@link streamingTable}.
+     */
+    table(spec: TableSpec): this;
+    /**
+     * Begin a streaming table. Uses the native row-at-a-time FFI
+     * (`pdf_page_builder_streaming_table_begin_v2`). Pass a `mode` in
+     * `config` to control column-sizing strategy (default: fixed widths).
+     */
+    streamingTable(config: StreamingTableConfig): StreamingTable;
+    /** @internal — open streaming table FFI handle on this page. */
+    _streamingTableBeginV2(headers: string[], widths: number[], aligns: number[], repeatHeader: boolean, mode: TableMode | undefined, maxRowspan: number): void;
+    /** @internal — push one row into the open streaming table (all rowspan=1). */
+    _streamingTablePushRow(cells: Array<string | null>): void;
+    /** @internal — push one row with per-cell rowspan values. */
+    _streamingTablePushRowV2(cells: Array<[string | null, number]>): void;
+    /** @internal — close the open streaming table. */
+    _streamingTableFinish(): void;
+    /** @internal — track the last font size for JS-side `measure()`. */
+    _lastFontSize?: number;
+    /**
+     * Commit the page's buffered operations to the parent builder and
+     * return the parent for chaining. After `done()` this PageBuilder is
+     * invalid.
+     */
+    done(): DocumentBuilder;
+    /**
+     * Drop an uncommitted page. Use only for error recovery — the parent's
+     * open-page slot is released so the next `a4Page()` etc. succeeds.
+     */
+    close(): void;
+    /** Symbol.dispose support for `using`. */
+    [Symbol.dispose](): void;
+}
+export { StreamingTable } from './streaming-table.js';
+export { Align, type Column, type SpanCell, type StreamingTableConfig, type TableMode, type TableSpec, };