@ironsoftware/ironpdf 2026.3.1 → 2026.5.1

package/src/public/annotation.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Destination type that controls how a PDF reader displays the target page when a
+ * bookmark or internal hyperlink is followed.
+ *
+ * Mirrors {@code IronPdf.Bookmarks.BookmarkDestinations} on the C# side. The numeric
+ * value of each entry is what the engine expects on the wire, so the order must match
+ * the C# enum.
+ *
+ * Corresponds to the PDF 1.7 specification §12.3.2 "Explicit Destinations".
+ */
+export declare enum BookmarkDestinations {
+    /**
+     * Fit the entire destination page within the window (PDF {@code /Fit}).
+     * No additional coordinates are used.
+     */
+    Page = 0,
+    /**
+     * Scroll to a specific Y coordinate on the destination page while fitting the
+     * page width to the window (PDF {@code /FitH}).
+     * Uses {@link LinkAnnotation.destinationTop}.
+     */
+    PageY = 1,
+    /**
+     * Scroll to a specific X coordinate on the destination page while fitting the
+     * page height to the window (PDF {@code /FitV}).
+     * Uses {@link LinkAnnotation.destinationLeft}.
+     */
+    PageX = 2,
+    /**
+     * Scroll to a specific position and zoom level (PDF {@code /XYZ}).
+     * Uses {@link LinkAnnotation.destinationLeft}, {@link LinkAnnotation.destinationTop},
+     * and {@link LinkAnnotation.destinationZoom}. A {@code destinationZoom} of 0 means
+     * "inherit the current zoom".
+     */
+    PageZoom = 3,
+    /**
+     * Fit the specified rectangle of the destination page into the window (PDF {@code /FitR}).
+     * Uses {@link LinkAnnotation.destinationLeft}, {@link LinkAnnotation.destinationBottom},
+     * {@link LinkAnnotation.destinationRight}, and {@link LinkAnnotation.destinationTop}.
+     */
+    PageRect = 4,
+    /**
+     * Fit the bounding box of the destination page into the window (PDF {@code /FitB}).
+     */
+    PageBounds = 5,
+    /**
+     * Scroll to a Y coordinate while fitting the bounding box width to the window
+     * (PDF {@code /FitBH}). Uses {@link LinkAnnotation.destinationTop}.
+     */
+    PageBoundsY = 6,
+    /**
+     * Scroll to an X coordinate while fitting the bounding box height to the window
+     * (PDF {@code /FitBV}). Uses {@link LinkAnnotation.destinationLeft}.
+     */
+    PageBoundsX = 7
+}
+/**
+ * Defines a clickable link annotation that navigates to a specific page within the same
+ * PDF document. Useful for building custom tables of contents, cross-references, and
+ * in-document navigation.
+ *
+ * Mirrors {@code IronPdf.Annotations.LinkAnnotation} on the C# side.
+ *
+ * @example
+ * ```ts
+ * // Simple TOC link: from page 0 to page 3
+ * await pdf.addLinkAnnotation({
+ *     pageIndex: 0,
+ *     destinationPageIndex: 3,
+ *     x: 72, y: 700,
+ *     width: 300, height: 18,
+ *     contents: "Chapter 1 - Introduction",
+ * });
+ *
+ * // Scroll-to-position link: jump to y=400 on page 1
+ * await pdf.addLinkAnnotation({
+ *     pageIndex: 0,
+ *     destinationPageIndex: 1,
+ *     destinationType: BookmarkDestinations.PageZoom,
+ *     destinationTop: 400,
+ *     destinationZoom: 100,
+ *     x: 72, y: 650,
+ *     width: 300, height: 18,
+ * });
+ * ```
+ *
+ * <b>Coordinate note:</b> {@code y} sets the <em>bottom</em> edge of the clickable area
+ * using PDF coordinates (origin at bottom-left of page).
+ */
+export interface LinkAnnotation {
+    /** Zero-based index of the page where the link is placed. */
+    pageIndex: number;
+    /** Zero-based index of the page to navigate to when clicked. */
+    destinationPageIndex: number;
+    /**
+     * Destination type controlling how the target page is displayed.
+     * @default BookmarkDestinations.Page
+     */
+    destinationType?: BookmarkDestinations;
+    /**
+     * Left coordinate of the destination position, in points.
+     * Used by {@link BookmarkDestinations.PageZoom}, {@link BookmarkDestinations.PageX},
+     * {@link BookmarkDestinations.PageRect}, and {@link BookmarkDestinations.PageBoundsX}.
+     */
+    destinationLeft?: number;
+    /**
+     * Right coordinate of the destination position, in points.
+     * Used by {@link BookmarkDestinations.PageRect}.
+     */
+    destinationRight?: number;
+    /**
+     * Top coordinate of the destination position, in points.
+     * Used by {@link BookmarkDestinations.PageZoom}, {@link BookmarkDestinations.PageY},
+     * {@link BookmarkDestinations.PageRect}, and {@link BookmarkDestinations.PageBoundsY}.
+     */
+    destinationTop?: number;
+    /**
+     * Bottom coordinate of the destination position, in points.
+     * Used by {@link BookmarkDestinations.PageRect}.
+     */
+    destinationBottom?: number;
+    /**
+     * Zoom level (in percent) for the destination. Used by
+     * {@link BookmarkDestinations.PageZoom}. A value of 0 means inherit the current zoom.
+     */
+    destinationZoom?: number;
+    /**
+     * Horizontal X position from the LEFT edge of the page, in points.
+     */
+    x: number;
+    /**
+     * Vertical Y position from the BOTTOM edge of the page, in points.
+     * PDF coordinate system places Y=0 at the bottom of the page.
+     */
+    y: number;
+    /** Width of the clickable link area, in points. */
+    width: number;
+    /** Height of the clickable link area, in points. */
+    height: number;
+    /**
+     * Color code for the link border in CSS `#RRGGBB` format.
+     * @default undefined (no explicit color)
+     */
+    colorCode?: string;
+    /**
+     * Whether the link annotation is hidden from users.
+     * @default false
+     */
+    hidden?: boolean;
+    /**
+     * Descriptive text content for this link annotation.
+     * @default ""
+     */
+    contents?: string;
+    /**
+     * Title for this link annotation.
+     * @default ""
+     */
+    title?: string;
+    /**
+     * Whether the link annotation displays a visible border when clicked.
+     * @default false
+     */
+    showBorder?: boolean;
+}
+//# sourceMappingURL=annotation.d.ts.map

package/src/public/annotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation.d.ts","sourceRoot":"","sources":["annotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,oBAAY,oBAAoB;IAC/B;;;OAGG;IACH,IAAI,IAAI;IACR;;;;OAIG;IACH,KAAK,IAAI;IACT;;;;OAIG;IACH,KAAK,IAAI;IACT;;;;;OAKG;IACH,QAAQ,IAAI;IACZ;;;;OAIG;IACH,QAAQ,IAAI;IACZ;;OAEG;IACH,UAAU,IAAI;IACd;;;OAGG;IACH,WAAW,IAAI;IACf;;;OAGG;IACH,WAAW,IAAI;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,cAAc;IAC9B,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,eAAe,CAAC,EAAE,oBAAoB,CAAC;IACvC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,CAAC,EAAE,MAAM,CAAC;IACV;;;OAGG;IACH,CAAC,EAAE,MAAM,CAAC;IACV,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB"}

package/src/public/annotation.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BookmarkDestinations = void 0;
+/**
+ * Destination type that controls how a PDF reader displays the target page when a
+ * bookmark or internal hyperlink is followed.
+ *
+ * Mirrors {@code IronPdf.Bookmarks.BookmarkDestinations} on the C# side. The numeric
+ * value of each entry is what the engine expects on the wire, so the order must match
+ * the C# enum.
+ *
+ * Corresponds to the PDF 1.7 specification §12.3.2 "Explicit Destinations".
+ */
+var BookmarkDestinations;
+(function (BookmarkDestinations) {
+    /**
+     * Fit the entire destination page within the window (PDF {@code /Fit}).
+     * No additional coordinates are used.
+     */
+    BookmarkDestinations[BookmarkDestinations["Page"] = 0] = "Page";
+    /**
+     * Scroll to a specific Y coordinate on the destination page while fitting the
+     * page width to the window (PDF {@code /FitH}).
+     * Uses {@link LinkAnnotation.destinationTop}.
+     */
+    BookmarkDestinations[BookmarkDestinations["PageY"] = 1] = "PageY";
+    /**
+     * Scroll to a specific X coordinate on the destination page while fitting the
+     * page height to the window (PDF {@code /FitV}).
+     * Uses {@link LinkAnnotation.destinationLeft}.
+     */
+    BookmarkDestinations[BookmarkDestinations["PageX"] = 2] = "PageX";
+    /**
+     * Scroll to a specific position and zoom level (PDF {@code /XYZ}).
+     * Uses {@link LinkAnnotation.destinationLeft}, {@link LinkAnnotation.destinationTop},
+     * and {@link LinkAnnotation.destinationZoom}. A {@code destinationZoom} of 0 means
+     * "inherit the current zoom".
+     */
+    BookmarkDestinations[BookmarkDestinations["PageZoom"] = 3] = "PageZoom";
+    /**
+     * Fit the specified rectangle of the destination page into the window (PDF {@code /FitR}).
+     * Uses {@link LinkAnnotation.destinationLeft}, {@link LinkAnnotation.destinationBottom},
+     * {@link LinkAnnotation.destinationRight}, and {@link LinkAnnotation.destinationTop}.
+     */
+    BookmarkDestinations[BookmarkDestinations["PageRect"] = 4] = "PageRect";
+    /**
+     * Fit the bounding box of the destination page into the window (PDF {@code /FitB}).
+     */
+    BookmarkDestinations[BookmarkDestinations["PageBounds"] = 5] = "PageBounds";
+    /**
+     * Scroll to a Y coordinate while fitting the bounding box width to the window
+     * (PDF {@code /FitBH}). Uses {@link LinkAnnotation.destinationTop}.
+     */
+    BookmarkDestinations[BookmarkDestinations["PageBoundsY"] = 6] = "PageBoundsY";
+    /**
+     * Scroll to an X coordinate while fitting the bounding box height to the window
+     * (PDF {@code /FitBV}). Uses {@link LinkAnnotation.destinationLeft}.
+     */
+    BookmarkDestinations[BookmarkDestinations["PageBoundsX"] = 7] = "PageBoundsX";
+})(BookmarkDestinations = exports.BookmarkDestinations || (exports.BookmarkDestinations = {}));
+//# sourceMappingURL=annotation.js.map

package/src/public/annotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation.js","sourceRoot":"","sources":["annotation.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;GASG;AACH,IAAY,oBA6CX;AA7CD,WAAY,oBAAoB;IAC/B;;;OAGG;IACH,+DAAQ,CAAA;IACR;;;;OAIG;IACH,iEAAS,CAAA;IACT;;;;OAIG;IACH,iEAAS,CAAA;IACT;;;;;OAKG;IACH,uEAAY,CAAA;IACZ;;;;OAIG;IACH,uEAAY,CAAA;IACZ;;OAEG;IACH,2EAAc,CAAA;IACd;;;OAGG;IACH,6EAAe,CAAA;IACf;;;OAGG;IACH,6EAAe,CAAA;AAChB,CAAC,EA7CW,oBAAoB,GAApB,4BAAoB,KAApB,4BAAoB,QA6C/B"}

package/src/public/annotation.ts

@@ -0,0 +1,166 @@
+/**
+ * Destination type that controls how a PDF reader displays the target page when a
+ * bookmark or internal hyperlink is followed.
+ *
+ * Mirrors {@code IronPdf.Bookmarks.BookmarkDestinations} on the C# side. The numeric
+ * value of each entry is what the engine expects on the wire, so the order must match
+ * the C# enum.
+ *
+ * Corresponds to the PDF 1.7 specification §12.3.2 "Explicit Destinations".
+ */
+export enum BookmarkDestinations {
+	/**
+	 * Fit the entire destination page within the window (PDF {@code /Fit}).
+	 * No additional coordinates are used.
+	 */
+	Page = 0,
+	/**
+	 * Scroll to a specific Y coordinate on the destination page while fitting the
+	 * page width to the window (PDF {@code /FitH}).
+	 * Uses {@link LinkAnnotation.destinationTop}.
+	 */
+	PageY = 1,
+	/**
+	 * Scroll to a specific X coordinate on the destination page while fitting the
+	 * page height to the window (PDF {@code /FitV}).
+	 * Uses {@link LinkAnnotation.destinationLeft}.
+	 */
+	PageX = 2,
+	/**
+	 * Scroll to a specific position and zoom level (PDF {@code /XYZ}).
+	 * Uses {@link LinkAnnotation.destinationLeft}, {@link LinkAnnotation.destinationTop},
+	 * and {@link LinkAnnotation.destinationZoom}. A {@code destinationZoom} of 0 means
+	 * "inherit the current zoom".
+	 */
+	PageZoom = 3,
+	/**
+	 * Fit the specified rectangle of the destination page into the window (PDF {@code /FitR}).
+	 * Uses {@link LinkAnnotation.destinationLeft}, {@link LinkAnnotation.destinationBottom},
+	 * {@link LinkAnnotation.destinationRight}, and {@link LinkAnnotation.destinationTop}.
+	 */
+	PageRect = 4,
+	/**
+	 * Fit the bounding box of the destination page into the window (PDF {@code /FitB}).
+	 */
+	PageBounds = 5,
+	/**
+	 * Scroll to a Y coordinate while fitting the bounding box width to the window
+	 * (PDF {@code /FitBH}). Uses {@link LinkAnnotation.destinationTop}.
+	 */
+	PageBoundsY = 6,
+	/**
+	 * Scroll to an X coordinate while fitting the bounding box height to the window
+	 * (PDF {@code /FitBV}). Uses {@link LinkAnnotation.destinationLeft}.
+	 */
+	PageBoundsX = 7,
+}
+ 
+/**
+ * Defines a clickable link annotation that navigates to a specific page within the same
+ * PDF document. Useful for building custom tables of contents, cross-references, and
+ * in-document navigation.
+ *
+ * Mirrors {@code IronPdf.Annotations.LinkAnnotation} on the C# side.
+ *
+ * @example
+ * ```ts
+ * // Simple TOC link: from page 0 to page 3
+ * await pdf.addLinkAnnotation({
+ *     pageIndex: 0,
+ *     destinationPageIndex: 3,
+ *     x: 72, y: 700,
+ *     width: 300, height: 18,
+ *     contents: "Chapter 1 - Introduction",
+ * });
+ *
+ * // Scroll-to-position link: jump to y=400 on page 1
+ * await pdf.addLinkAnnotation({
+ *     pageIndex: 0,
+ *     destinationPageIndex: 1,
+ *     destinationType: BookmarkDestinations.PageZoom,
+ *     destinationTop: 400,
+ *     destinationZoom: 100,
+ *     x: 72, y: 650,
+ *     width: 300, height: 18,
+ * });
+ * ```
+ *
+ * <b>Coordinate note:</b> {@code y} sets the <em>bottom</em> edge of the clickable area
+ * using PDF coordinates (origin at bottom-left of page).
+ */
+export interface LinkAnnotation {
+	/** Zero-based index of the page where the link is placed. */
+	pageIndex: number;
+	/** Zero-based index of the page to navigate to when clicked. */
+	destinationPageIndex: number;
+	/**
+	 * Destination type controlling how the target page is displayed.
+	 * @default BookmarkDestinations.Page
+	 */
+	destinationType?: BookmarkDestinations;
+	/**
+	 * Left coordinate of the destination position, in points.
+	 * Used by {@link BookmarkDestinations.PageZoom}, {@link BookmarkDestinations.PageX},
+	 * {@link BookmarkDestinations.PageRect}, and {@link BookmarkDestinations.PageBoundsX}.
+	 */
+	destinationLeft?: number;
+	/**
+	 * Right coordinate of the destination position, in points.
+	 * Used by {@link BookmarkDestinations.PageRect}.
+	 */
+	destinationRight?: number;
+	/**
+	 * Top coordinate of the destination position, in points.
+	 * Used by {@link BookmarkDestinations.PageZoom}, {@link BookmarkDestinations.PageY},
+	 * {@link BookmarkDestinations.PageRect}, and {@link BookmarkDestinations.PageBoundsY}.
+	 */
+	destinationTop?: number;
+	/**
+	 * Bottom coordinate of the destination position, in points.
+	 * Used by {@link BookmarkDestinations.PageRect}.
+	 */
+	destinationBottom?: number;
+	/**
+	 * Zoom level (in percent) for the destination. Used by
+	 * {@link BookmarkDestinations.PageZoom}. A value of 0 means inherit the current zoom.
+	 */
+	destinationZoom?: number;
+	/**
+	 * Horizontal X position from the LEFT edge of the page, in points.
+	 */
+	x: number;
+	/**
+	 * Vertical Y position from the BOTTOM edge of the page, in points.
+	 * PDF coordinate system places Y=0 at the bottom of the page.
+	 */
+	y: number;
+	/** Width of the clickable link area, in points. */
+	width: number;
+	/** Height of the clickable link area, in points. */
+	height: number;
+	/**
+	 * Color code for the link border in CSS `#RRGGBB` format.
+	 * @default undefined (no explicit color)
+	 */
+	colorCode?: string;
+	/**
+	 * Whether the link annotation is hidden from users.
+	 * @default false
+	 */
+	hidden?: boolean;
+	/**
+	 * Descriptive text content for this link annotation.
+	 * @default ""
+	 */
+	contents?: string;
+	/**
+	 * Title for this link annotation.
+	 * @default ""
+	 */
+	title?: string;
+	/**
+	 * Whether the link annotation displays a visible border when clicked.
+	 * @default false
+	 */
+	showBorder?: boolean;
+}

package/src/public/bookmark.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A single PDF bookmark (outline entry). Mirrors the C# {@code IronPdf.Bookmark}
+ * shape — flat structure with parent linkage instead of nested children.
+ *
+ * <p>Returned by {@link PdfDocument.getBookmarks}. Hierarchy is conveyed via
+ * {@link parentItemId} (a bookmark's parent has matching {@link itemId}) and
+ * {@link hierarchy} (a path-like string describing depth in the outline tree).</p>
+ */
+export interface Bookmark {
+    /** Human-readable label shown in the PDF reader's bookmark panel. */
+    text: string;
+    /** Zero-based page index this bookmark navigates to. */
+    pageIndex: number;
+    /**
+     * Path-like string describing this bookmark's depth in the outline tree.
+     * Empty string for roots; nested entries have something like "0/1" or
+     * "Chapter 1/Section 1.1" depending on engine encoding.
+     */
+    hierarchy: string;
+    /** Stable identifier for this bookmark within the document. */
+    itemId: string;
+    /** {@link itemId} of the parent bookmark, or empty string for roots. */
+    parentItemId: string;
+}
+//# sourceMappingURL=bookmark.d.ts.map

package/src/public/bookmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bookmark.d.ts","sourceRoot":"","sources":["bookmark.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACxB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IAEb,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IAEf,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;CACrB"}

package/src/public/bookmark.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=bookmark.js.map

package/src/public/bookmark.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bookmark.js","sourceRoot":"","sources":["bookmark.ts"],"names":[],"mappings":""}

package/src/public/bookmark.ts

@@ -0,0 +1,28 @@
+/**
+ * A single PDF bookmark (outline entry). Mirrors the C# {@code IronPdf.Bookmark}
+ * shape — flat structure with parent linkage instead of nested children.
+ *
+ * <p>Returned by {@link PdfDocument.getBookmarks}. Hierarchy is conveyed via
+ * {@link parentItemId} (a bookmark's parent has matching {@link itemId}) and
+ * {@link hierarchy} (a path-like string describing depth in the outline tree).</p>
+ */
+export interface Bookmark {
+	/** Human-readable label shown in the PDF reader's bookmark panel. */
+	text: string;
+
+	/** Zero-based page index this bookmark navigates to. */
+	pageIndex: number;
+
+	/**
+	 * Path-like string describing this bookmark's depth in the outline tree.
+	 * Empty string for roots; nested entries have something like "0/1" or
+	 * "Chapter 1/Section 1.1" depending on engine encoding.
+	 */
+	hierarchy: string;
+
+	/** Stable identifier for this bookmark within the document. */
+	itemId: string;
+
+	/** {@link itemId} of the parent bookmark, or empty string for roots. */
+	parentItemId: string;
+}