@qrcommunication/gigapdf-lib 0.1.0 → 0.8.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
- * @giga-pdf/wasm-engine — TypeScript SDK for the zero-dependency Rust→WASM PDF
- * engine (gigapdf-engine). Wraps the flat `extern "C"` `gp_*` ABI behind a typed,
+ * @qrcommunication/gigapdf-lib — TypeScript SDK for the zero-dependency Rust→WASM
+ * PDF engine (gigapdf-lib). Wraps the flat `extern "C"` `gp_*` ABI behind a typed,
  * ergonomic class. No third-party runtime deps; the `.wasm` is self-contained.
  *
  * Usage:
@@ -42,6 +42,8 @@ declare class GigaPdfEngine {
     _json<T = unknown>(call: (outLenPtr: number) => number): T;
     /** Pass a string argument; runs `fn(ptr, len)` then frees. */
     _withStr<T>(s: string, fn: (ptr: number, len: number) => T): T;
+    /** Pass an optional string; an absent/empty value runs `fn(0, 0)` (no alloc). */
+    _withOptStr<T>(s: string | undefined, fn: (ptr: number, len: number) => T): T;
     /** Pass a bytes argument; runs `fn(ptr, len)` then frees. */
     _withBytes<T>(bytes: Uint8Array, fn: (ptr: number, len: number) => T): T;
     /** Pass a `u32[]` argument (e.g. page numbers); runs `fn(ptr, count)` then frees. */
@@ -63,6 +65,102 @@ declare class GigaPdfEngine {
     fontRequestUrl(family: string, weight?: number, italic?: boolean): string;
     /** Extract the trusted gstatic font URL from a Google Fonts CSS2 response. */
     parseCssFontUrl(css: string): string;
+    /**
+     * Evaluate a JavaScript snippet with the built-in engine and return the
+     * result value as a string (or `Uncaught …` / `SyntaxError: …`).
+     */
+    evalJs(src: string): string;
+    /**
+     * Run a document's inline `<script>`s and return the resulting HTML. The
+     * `htmlRender`/`htmlNeededFonts` paths already do this automatically; use this
+     * only when you want the post-script HTML on its own.
+     */
+    runInlineScripts(html: string): string;
+    /**
+     * Phase 1 — the Google fonts the document references. Download each `url`
+     * (→ TTF) and pass the bytes back to {@link htmlRender} for an identical render.
+     */
+    htmlNeededFonts(html: string): HtmlFontRequest[];
+    /**
+     * Phase 2 — render HTML + CSS to PDF, with the supplied fonts embedded (real
+     * Google fonts, real metrics → identical or nearest match). Block, inline and
+     * table layout with pagination. Page size and margin are in points
+     * (US-Letter portrait, 0.5in margins by default). JavaScript is not executed.
+     */
+    htmlRender(html: string, fonts?: HtmlFont[], pageWidth?: number, pageHeight?: number, margin?: number): Uint8Array;
+    /**
+     * Resolve a named paper size — `"A4"`, `"a3-landscape"`, `"letter"`, `"legal"`,
+     * `"tabloid"`, `"b5"`, … — to `{ w, h }` in points (portrait unless the name
+     * has a `-landscape` suffix). Returns `null` for an unknown name.
+     */
+    pageSize(name: string): {
+        w: number;
+        h: number;
+    } | null;
+    /**
+     * Phase 1 variant that also scans the running `header`/`footer` HTML, so the
+     * Google fonts they reference are requested alongside the body's.
+     */
+    htmlNeededFontsWith(html: string, header?: string, footer?: string): HtmlFontRequest[];
+    /**
+     * Phase 2 with full page control: named/explicit size, per-side margins, and a
+     * running header/footer painted in the page margins. `{{page}}` and `{{pages}}`
+     * in the header/footer are replaced with the current / total page number.
+     *
+     * ```ts
+     * const fonts = await fetchFonts(giga.htmlNeededFontsWith(html, header, footer));
+     * const pdf = giga.htmlRenderWith(html, fonts, {
+     *   pageSize: "A4",
+     *   margin: { top: 72, bottom: 72, left: 54, right: 54 },
+     *   header: `<div style="text-align:center">My Report</div>`,
+     *   footer: `<div style="text-align:center">Page {{page}} / {{pages}}</div>`,
+     * });
+     * ```
+     */
+    htmlRenderWith(html: string, fonts?: HtmlFont[], options?: HtmlRenderOptions): Uint8Array;
+}
+/** A Google font the HTML engine needs (resolved from the catalogue). */
+interface HtmlFontRequest {
+    family: string;
+    weight: number;
+    italic: boolean;
+    /** Google Fonts CSS URL — the host fetches it to obtain the TTF. */
+    url: string;
+}
+/** A downloaded font handed to {@link GigaPdfEngine.htmlRender}. */
+interface HtmlFont {
+    family: string;
+    weight: number;
+    italic: boolean;
+    ttf: Uint8Array;
+}
+/** Per-side page margins in points; omitted sides default to 36pt. */
+interface HtmlMargins {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+/** Page setup for {@link GigaPdfEngine.htmlRenderWith}. */
+interface HtmlRenderOptions {
+    /** Named paper size (`"A4"`, `"a3-landscape"`, `"letter"`, …) — wins over width/height. */
+    pageSize?: string;
+    /** Explicit page width in points (default 612 = US Letter). Ignored if `pageSize` is set. */
+    pageWidth?: number;
+    /** Explicit page height in points (default 792). Ignored if `pageSize` is set. */
+    pageHeight?: number;
+    /** Uniform margin (points) or per-side margins. Default 36pt (0.5in). */
+    margin?: number | HtmlMargins;
+    /** Running header HTML painted in the top margin (`{{page}}` / `{{pages}}` tokens). */
+    header?: string;
+    /** Running footer HTML painted in the bottom margin (same tokens). */
+    footer?: string;
+    /** Distance from the top edge to the header block, in points (default 18). */
+    headerOffset?: number;
+    /** Distance from the bottom edge to the footer block, in points (default 18). */
+    footerOffset?: number;
+    /** Number assigned to the first page for `{{page}}` (default 1). */
+    startPageNumber?: number;
 }
 interface FontInfo {
     family: string;
@@ -152,6 +250,26 @@ interface PageInfo {
     height: number;
     rotation: number;
 }
+/** Visual styling for a newly-created form field. */
+interface FieldStyle {
+    /** Text size in points; `0` (default) auto-sizes to the field box. */
+    fontSize?: number;
+    /** Text / mark colour `0xRRGGBB` (default black). */
+    color?: number;
+    /** Border colour `0xRRGGBB`, or `null` for no border (default black). */
+    border?: number | null;
+    /** Background fill `0xRRGGBB`, or `null` for transparent (default none). */
+    background?: number | null;
+    /** Border width in points (default `1`). */
+    borderWidth?: number;
+}
+/** One option of a radio group: its export value and on-page rectangle. */
+interface RadioOption {
+    /** The export value stored in the field when this button is selected. */
+    export: string;
+    /** `[x0, y0, x1, y1]` in PDF user space. */
+    rect: [number, number, number, number];
+}
 /** A live document handle. Call {@link close} when done. */
 declare class GigaPdfDoc {
     private readonly g;
@@ -179,7 +297,37 @@ declare class GigaPdfDoc {
      * Draw a vector rectangle. Pass an `0xRRGGBB` colour for `stroke`/`fill`, or
      * `null` to omit that paint. 0 → success.
      */
-    addRectangle(page: number, x: number, y: number, w: number, h: number, stroke?: number | null, fill?: number | null, lineWidth?: number): boolean;
+    addRectangle(page: number, x: number, y: number, w: number, h: number, stroke?: number | null, fill?: number | null, lineWidth?: number, opacity?: number): boolean;
+    /** Draw a straight line from `(x1,y1)` to `(x2,y2)`. `stroke` is `0xRRGGBB`. */
+    drawLine(page: number, x1: number, y1: number, x2: number, y2: number, stroke?: number, lineWidth?: number, opacity?: number): boolean;
+    /**
+     * Draw an ellipse (circle when `rx === ry`) centred at `(cx,cy)`. Pass an
+     * `0xRRGGBB` colour for `stroke`/`fill`, or `null` to omit that paint.
+     */
+    addEllipse(page: number, cx: number, cy: number, rx: number, ry: number, stroke?: number | null, fill?: number | null, lineWidth?: number, opacity?: number): boolean;
+    /**
+     * Draw a polyline/polygon through flat `[x0,y0,x1,y1,…]` points. `close` joins
+     * the last vertex back to the first. `0xRRGGBB` colours, or `null` to omit.
+     */
+    addPolygon(page: number, points: number[], close?: boolean, stroke?: number | null, fill?: number | null, lineWidth?: number, opacity?: number): boolean;
+    /**
+     * Draw an SVG path (`M`/`L`/`C`/`Q`/`Z`…) anchored so the SVG origin maps to
+     * `(ox,oy)` with the Y axis flipped — same convention as `pdf-lib`'s
+     * `drawSvgPath`. Covers freeform/polygon/triangle shapes.
+     */
+    addPath(page: number, svgPath: string, ox: number, oy: number, stroke?: number | null, fill?: number | null, lineWidth?: number, opacity?: number): boolean;
+    /**
+     * Embed a raster image (PNG or JPEG bytes) at `(x,y)` sized `(w,h)` in PDF
+     * user space. PNG alpha is honoured; `opacity` (0..1) sets an overall alpha.
+     */
+    addImage(page: number, data: Uint8Array, x: number, y: number, w: number, h: number, opacity?: number): boolean;
+    /**
+     * Draw SVG markup on a page as **native vector paths** (crisp at any zoom, not
+     * rasterized), fitting its `viewBox` into the box `(x, y, w, h)` in PDF points
+     * (origin bottom-left). Supports shapes, `<path>`, groups, transforms and
+     * fill/stroke/opacity. Returns `false` if the SVG can't be parsed.
+     */
+    addSvg(page: number, svg: string, x: number, y: number, w: number, h: number): boolean;
     /** True redaction: delete content intersecting the region (no opaque cover by default). */
     redact(page: number, x: number, y: number, w: number, h: number, coverRgb?: number, hasCover?: boolean): number;
     rotatePage(page: number, degrees: number): boolean;
@@ -204,12 +352,26 @@ declare class GigaPdfDoc {
     toHtml(): string;
     toDocx(): Uint8Array;
     toPptx(): Uint8Array;
+    /** Convert to an editable OpenDocument Presentation (`.odp`). */
+    toOdp(): Uint8Array;
     toOdt(): Uint8Array;
     toXlsx(): Uint8Array;
     toOds(): Uint8Array;
     toRtf(): Uint8Array;
     toPdfA(): Uint8Array;
-    saveEncrypted(password: string, fileId: string, permissions?: number): Uint8Array;
+    /**
+     * Serialize the document encrypted with the PDF Standard Security Handler.
+     * Defaults to **AES-256 (R6)**. `fileId` is the document `/ID` (any stable
+     * hex/string). For AES-256 a **secret 32-byte key** is required — it is taken
+     * from `opts.keySeed` or generated with Web Crypto; RC4/AES-128 derive their
+     * key from the password and ignore it.
+     */
+    saveEncrypted(password: string, fileId: string, opts?: {
+        ownerPassword?: string;
+        algorithm?: "rc4" | "aes128" | "aes256";
+        permissions?: number;
+        keySeed?: Uint8Array;
+    }): Uint8Array;
     /** Self-signed digital signature. `random` ≥ 256 bytes from crypto.getRandomValues. */
     sign(fields: string, random: Uint8Array, keyBits?: number): Uint8Array;
     getMetadata(key: string): string;
@@ -245,6 +407,42 @@ declare class GigaPdfDoc {
     setRadio(name: string, value: string): boolean;
     /** Set a choice field's selection (multi-select list boxes accept several values). */
     setChoice(name: string, values: string[]): boolean;
+    /**
+     * Create a text field on `page` covering `rect` = `[x0, y0, x1, y1]` (PDF
+     * user space). Options: `maxLen` character cap, `multiline`, `password`,
+     * and visual `style`.
+     */
+    addTextField(page: number, name: string, rect: [number, number, number, number], value?: string, opts?: {
+        maxLen?: number;
+        multiline?: boolean;
+        password?: boolean;
+        style?: FieldStyle;
+    }): boolean;
+    /** Create a checkbox. `export` is the on-state name (default `On`). */
+    addCheckbox(page: number, name: string, rect: [number, number, number, number], checked?: boolean, opts?: {
+        export?: string;
+        style?: FieldStyle;
+    }): boolean;
+    /**
+     * Create a radio-button group: one logical field whose `options` are the
+     * individual buttons. `selected` is the initially-chosen export value.
+     */
+    addRadioGroup(page: number, name: string, options: RadioOption[], opts?: {
+        selected?: string;
+        style?: FieldStyle;
+    }): boolean;
+    /** Create a drop-down combo box. `editable` permits values outside `options`. */
+    addComboBox(page: number, name: string, rect: [number, number, number, number], options: string[], opts?: {
+        selected?: string;
+        editable?: boolean;
+        style?: FieldStyle;
+    }): boolean;
+    /** Create a scrolling list box. `multi` allows selecting several options. */
+    addListBox(page: number, name: string, rect: [number, number, number, number], options: string[], opts?: {
+        selected?: string;
+        multi?: boolean;
+        style?: FieldStyle;
+    }): boolean;
 }
 
-export { type AnnotationInfo, type Box, type Element, type FieldInfo, type FieldKind, type FontInfo, GigaPdfDoc, GigaPdfEngine, type LayerInfo, type LinkInfo, type OcrWord, type OutlineEntry, type PageInfo, type SearchHit, type TextLine, type TextRunInfo };
+export { type AnnotationInfo, type Box, type Element, type FieldInfo, type FieldKind, type FieldStyle, type FontInfo, GigaPdfDoc, GigaPdfEngine, type HtmlFont, type HtmlFontRequest, type HtmlMargins, type HtmlRenderOptions, type LayerInfo, type LinkInfo, type OcrWord, type OutlineEntry, type PageInfo, type RadioOption, type SearchHit, type TextLine, type TextRunInfo };