@libpdf/core 0.2.1 → 0.2.3

package/README.md

@@ -2,13 +2,13 @@
 
 A modern PDF library for TypeScript. Parse, modify, and generate PDFs with a clean, intuitive API.
 
-> **Beta Software**: LibPDF is under active development. APIs may change between minor versions. Not yet recommended for production use.
+> **Beta Software**: LibPDF is under active development and APIs may change between minor versions, but we use it in production at [Documenso](https://documenso.com) and consider it ready for real-world use.
 
 ## Why LibPDF?
 
 LibPDF was born from frustration. At [Documenso](https://documenso.com), we found ourselves wrestling with the JavaScript PDF ecosystem:
 
-- **PDF.js** is excellent for rendering, but it's read-only
+- **PDF.js** is excellent for rendering and even has annotation editing — but it requires a browser
 - **pdf-lib** has a great API, but chokes on slightly malformed documents
 - **pdfkit** only generates, no parsing at all
 

package/dist/index.d.mts

@@ -3732,6 +3732,40 @@ interface FindTextOptions {
   wholeWord?: boolean;
 }
 //#endregion
+//#region src/svg/path-executor.d.ts
+/**
+ * Options for SVG path execution.
+ */
+interface SvgPathExecutorOptions {
+  /**
+   * Flip Y coordinates (negate Y values).
+   *
+   * SVG uses a top-left origin with Y increasing downward.
+   * PDF uses a bottom-left origin with Y increasing upward.
+   *
+   * When true (default), Y coordinates are negated to convert
+   * SVG paths to PDF coordinate space.
+   *
+   * @default true
+   */
+  flipY?: boolean;
+  /**
+   * Scale factor to apply to all coordinates.
+   * @default 1
+   */
+  scale?: number;
+  /**
+   * X offset to add after scaling and flipping.
+   * @default 0
+   */
+  translateX?: number;
+  /**
+   * Y offset to add after scaling and flipping.
+   * @default 0
+   */
+  translateY?: number;
+}
+//#endregion
 //#region src/fonts/standard-14.d.ts
 /**
  * Standard 14 PDF Fonts
@@ -3971,6 +4005,65 @@ interface DrawEllipseOptions {
   /** Rotation */
   rotate?: Rotation;
 }
+/**
+ * Options for drawing an SVG path.
+ *
+ * SVG paths are automatically transformed from SVG coordinate space
+ * (Y-down, origin at top-left) to PDF coordinate space (Y-up, origin
+ * at bottom-left). Use `x`, `y`, and `scale` to position and size
+ * the path on the page.
+ */
+interface DrawSvgPathOptions {
+  /**
+   * X position on the page (left edge of the path's bounding box).
+   * @default 0
+   */
+  x?: number;
+  /**
+   * Y position on the page (bottom edge of the path's bounding box after transform).
+   * @default 0
+   */
+  y?: number;
+  /**
+   * Scale factor to apply to the path.
+   * Useful for SVG icons with large viewBox (e.g., 512x512).
+   * A scale of 0.1 would make a 512-unit icon ~51 points.
+   * @default 1
+   */
+  scale?: number;
+  /**
+   * Whether to flip the Y-axis to convert from SVG coordinates (Y-down)
+   * to PDF coordinates (Y-up).
+   *
+   * Set to `true` (default) when using SVG paths from icon libraries.
+   * Set to `false` when using paths already in PDF coordinate space.
+   *
+   * @default true
+   */
+  flipY?: boolean;
+  /** Fill color (default: black; omit to stroke only if borderColor set) */
+  color?: Color;
+  /** Stroke color (omit for no stroke) */
+  borderColor?: Color;
+  /** Stroke width in points (default: 1 if borderColor set) */
+  borderWidth?: number;
+  /** Line cap style */
+  lineCap?: LineCap;
+  /** Line join style */
+  lineJoin?: LineJoin;
+  /** Miter limit for miter joins */
+  miterLimit?: number;
+  /** Dash pattern array */
+  dashArray?: number[];
+  /** Dash pattern phase */
+  dashPhase?: number;
+  /** Fill opacity 0-1 (default: 1) */
+  opacity?: number;
+  /** Stroke opacity 0-1 (default: 1) */
+  borderOpacity?: number;
+  /** Winding rule for fill (default: "nonzero") */
+  windingRule?: "nonzero" | "evenodd";
+}
 /**
  * Options for path painting.
  */
@@ -4093,6 +4186,40 @@ declare class PathBuilder {
    * Add an ellipse to the current path.
    */
   ellipse(cx: number, cy: number, rx: number, ry: number): this;
+  /**
+   * Append an SVG path string to the current path.
+   *
+   * Parses the SVG path `d` attribute string and adds all commands to this path.
+   * Relative commands (lowercase) are converted to absolute coordinates based on
+   * the current point. Smooth curves (S, T) and arcs (A) are converted to
+   * cubic bezier curves.
+   *
+   * By default, this method does NOT transform coordinates (flipY: false).
+   * Use the options to apply scale, translation, and Y-flip for SVG paths.
+   *
+   * @param pathData - SVG path `d` attribute string
+   * @param options - Execution options (flipY, scale, translate)
+   * @returns This PathBuilder for chaining
+   *
+   * @example
+   * ```typescript
+   * // Simple path (no transform)
+   * page.drawPath()
+   *   .appendSvgPath("M 10 10 L 100 10 L 55 90 Z")
+   *   .fill({ color: rgb(1, 0, 0) });
+   *
+   * // SVG icon with full transform
+   * page.drawPath()
+   *   .appendSvgPath(iconPath, {
+   *     flipY: true,
+   *     scale: 0.1,
+   *     translateX: 100,
+   *     translateY: 500,
+   *   })
+   *   .fill({ color: rgb(0, 0, 0) });
+   * ```
+   */
+  appendSvgPath(pathData: string, options?: SvgPathExecutorOptions): this;
   /**
    * Stroke the path with the given options.
    */
@@ -5204,6 +5331,49 @@ declare class PDFPage {
    * ```
    */
   drawPath(): PathBuilder;
+  /**
+   * Draw an SVG path on the page.
+   *
+   * This is a convenience method that parses an SVG path `d` attribute string
+   * and draws it with the specified options. For more control, use `drawPath()`
+   * with `appendSvgPath()`.
+   *
+   * By default, the path is filled with black. Specify `borderColor` without
+   * `color` to stroke without filling.
+   *
+   * SVG paths are automatically transformed from SVG coordinate space (Y-down)
+   * to PDF coordinate space (Y-up). Use `x`, `y` to position the path, and
+   * `scale` to resize it.
+   *
+   * @param pathData - SVG path `d` attribute string
+   * @param options - Drawing options (x, y, scale, color, etc.)
+   *
+   * @example
+   * ```typescript
+   * // Draw a Font Awesome heart icon at position (100, 500)
+   * // Icon is 512x512 in SVG, scale to ~50pt
+   * page.drawSvgPath(faHeartPath, {
+   *   x: 100,
+   *   y: 500,
+   *   scale: 0.1,
+   *   color: rgb(1, 0, 0),
+   * });
+   *
+   * // Draw a simple triangle at default position (0, 0)
+   * page.drawSvgPath("M 0 0 L 50 0 L 25 40 Z", {
+   *   color: rgb(0, 0, 1),
+   * });
+   *
+   * // Stroke a curve
+   * page.drawSvgPath("M 0 0 C 10 10, 30 10, 40 0", {
+   *   x: 200,
+   *   y: 300,
+   *   borderColor: rgb(0, 0, 0),
+   *   borderWidth: 2,
+   * });
+   * ```
+   */
+  drawSvgPath(pathData: string, options?: DrawSvgPathOptions): void;
   /** Cached annotations for this page */
   private _annotationCache;
   /**
@@ -9260,5 +9430,5 @@ declare function isWidgetAnnotation(dict: PdfDict, registry?: ObjectRegistry): b
  */
 declare function isPopupAnnotation(dict: PdfDict, registry?: ObjectRegistry): boolean;
 //#endregion
-export { AnnotationFlags, type AnnotationSubtype, type AuthenticationResult, type BorderStyle, type BorderStyleType, type ButtonField, type CMYK, type CaretAnnotationOptions, type CaretSymbol, CertificateChainError, type CheckboxField, type CheckboxOptions, type CheckboxSymbol, type CircleAnnotationOptions, type Color, type CopyPagesOptions, CryptoKeySigner, type Degrees, type DestinationType, type DigestAlgorithm, type DocumentMetadata, type DrawCircleOptions, type DrawEllipseOptions, type DrawFieldOptions, type DrawImageOptions, type DrawLineOptions, type DrawPageOptions, type DrawRectangleOptions, type DrawTextOptions, type DropdownField, type DropdownOptions, type EmbedFontOptions, type EmbeddedFont, type EncryptionAlgorithmOption, type ExtractPagesOptions, type FieldOptions, type FieldType, type FieldValue, type FileAttachmentIcon, type FlattenAllOptions, type FlattenAllResult, type FlattenAnnotationsOptions, type FlattenLayersResult, type FlattenOptions, type FontInput, type FormField, type FormProperties, type FreeTextAnnotationOptions, type FreeTextJustification, GoogleKmsSigner, type Grayscale, type HighlightMode, HttpTimestampAuthority, type HttpTimestampAuthorityOptions, type InkAnnotationOptions, type KeyType, KmsSignerError, type LayerInfo, type LayoutResult, type LineAnnotationOptions, type LineCap, type LineEndingStyle, type LineJoin, type LinkAction, type LinkAnnotationOptions, type LinkDestination, type ListBoxField, type ListboxOptions, type LoadOptions, type MergeOptions, P12Signer, type PAdESLevel, PDF, PDFAnnotation, PDFCaretAnnotation, PDFCircleAnnotation, PDFEmbeddedPage, PDFFileAttachmentAnnotation, PDFForm, PDFFreeTextAnnotation, PDFHighlightAnnotation, PDFImage, PDFInkAnnotation, PDFLineAnnotation, PDFLinkAnnotation, PDFMarkupAnnotation, PDFPage, PDFPolygonAnnotation, PDFPolylineAnnotation, PDFPopupAnnotation, PDFSquareAnnotation, PDFSquigglyAnnotation, PDFStampAnnotation, PDFStrikeOutAnnotation, PDFTextAnnotation, PDFTextMarkupAnnotation, PDFUnderlineAnnotation, PDFUnknownAnnotation, PathBuilder, type PathOptions, PdfArray, PdfBool, PdfDict, PdfName, PdfNull, PdfNumber, type PdfObject, PdfRef, PdfStream, PdfString, type PemBlock, PermissionDeniedError, type PermissionOptions, type Permissions, PlaceholderError, type Point, type PolygonAnnotationOptions, type PolylineAnnotationOptions, type PopupOptions, type PositionedWord, type ProtectionOptions, type RGB, type RadioField, type RadioGroupOptions, type RadioSymbol, type Rect, type Rectangle, type RemoveAnnotationsOptions, RevocationError, type RevocationProvider, type Rotation, type RotationOrigin, type RotationOriginName, STANDARD_STAMPS, type SaveOptions, SecurityError, type SecurityInfo, type SetTitleOptions, type SignOptions, type SignResult, type SignWarning, type SignatureAlgorithm, SignatureError, type SignatureField, type SignatureFieldOptions, type Signer, SignerError, type SquareAnnotationOptions, type StampAnnotationOptions, type StampName, Standard14Font, type Standard14FontName, StandardFonts, type SubFilter, type TextAlignment, type TextAnnotationIcon, type TextAnnotationOptions, type TextAnnotationState, type TextAnnotationStateModel, type TextField, type TextFieldOptions, type TextLine, type TextMarkupAnnotationOptions, type TimestampAuthority, TimestampError, type TrappedStatus, black, blue, cmyk, createAnnotation, degrees, grayscale, green, isPopupAnnotation, isWidgetAnnotation, layoutJustifiedLine, layoutText, lineCapToNumber, lineJoinToNumber, measureText, parsePem, rectToQuadPoints, rectsToQuadPoints, red, rgb, version, white };
+export { AnnotationFlags, type AnnotationSubtype, type AuthenticationResult, type BorderStyle, type BorderStyleType, type ButtonField, type CMYK, type CaretAnnotationOptions, type CaretSymbol, CertificateChainError, type CheckboxField, type CheckboxOptions, type CheckboxSymbol, type CircleAnnotationOptions, type Color, type CopyPagesOptions, CryptoKeySigner, type Degrees, type DestinationType, type DigestAlgorithm, type DocumentMetadata, type DrawCircleOptions, type DrawEllipseOptions, type DrawFieldOptions, type DrawImageOptions, type DrawLineOptions, type DrawPageOptions, type DrawRectangleOptions, type DrawSvgPathOptions, type DrawTextOptions, type DropdownField, type DropdownOptions, type EmbedFontOptions, type EmbeddedFont, type EncryptionAlgorithmOption, type ExtractPagesOptions, type FieldOptions, type FieldType, type FieldValue, type FileAttachmentIcon, type FlattenAllOptions, type FlattenAllResult, type FlattenAnnotationsOptions, type FlattenLayersResult, type FlattenOptions, type FontInput, type FormField, type FormProperties, type FreeTextAnnotationOptions, type FreeTextJustification, GoogleKmsSigner, type Grayscale, type HighlightMode, HttpTimestampAuthority, type HttpTimestampAuthorityOptions, type InkAnnotationOptions, type KeyType, KmsSignerError, type LayerInfo, type LayoutResult, type LineAnnotationOptions, type LineCap, type LineEndingStyle, type LineJoin, type LinkAction, type LinkAnnotationOptions, type LinkDestination, type ListBoxField, type ListboxOptions, type LoadOptions, type MergeOptions, P12Signer, type PAdESLevel, PDF, PDFAnnotation, PDFCaretAnnotation, PDFCircleAnnotation, PDFEmbeddedPage, PDFFileAttachmentAnnotation, PDFForm, PDFFreeTextAnnotation, PDFHighlightAnnotation, PDFImage, PDFInkAnnotation, PDFLineAnnotation, PDFLinkAnnotation, PDFMarkupAnnotation, PDFPage, PDFPolygonAnnotation, PDFPolylineAnnotation, PDFPopupAnnotation, PDFSquareAnnotation, PDFSquigglyAnnotation, PDFStampAnnotation, PDFStrikeOutAnnotation, PDFTextAnnotation, PDFTextMarkupAnnotation, PDFUnderlineAnnotation, PDFUnknownAnnotation, PathBuilder, type PathOptions, PdfArray, PdfBool, PdfDict, PdfName, PdfNull, PdfNumber, type PdfObject, PdfRef, PdfStream, PdfString, type PemBlock, PermissionDeniedError, type PermissionOptions, type Permissions, PlaceholderError, type Point, type PolygonAnnotationOptions, type PolylineAnnotationOptions, type PopupOptions, type PositionedWord, type ProtectionOptions, type RGB, type RadioField, type RadioGroupOptions, type RadioSymbol, type Rect, type Rectangle, type RemoveAnnotationsOptions, RevocationError, type RevocationProvider, type Rotation, type RotationOrigin, type RotationOriginName, STANDARD_STAMPS, type SaveOptions, SecurityError, type SecurityInfo, type SetTitleOptions, type SignOptions, type SignResult, type SignWarning, type SignatureAlgorithm, SignatureError, type SignatureField, type SignatureFieldOptions, type Signer, SignerError, type SquareAnnotationOptions, type StampAnnotationOptions, type StampName, Standard14Font, type Standard14FontName, StandardFonts, type SubFilter, type TextAlignment, type TextAnnotationIcon, type TextAnnotationOptions, type TextAnnotationState, type TextAnnotationStateModel, type TextField, type TextFieldOptions, type TextLine, type TextMarkupAnnotationOptions, type TimestampAuthority, TimestampError, type TrappedStatus, black, blue, cmyk, createAnnotation, degrees, grayscale, green, isPopupAnnotation, isWidgetAnnotation, layoutJustifiedLine, layoutText, lineCapToNumber, lineJoinToNumber, measureText, parsePem, rectToQuadPoints, rectsToQuadPoints, red, rgb, version, white };
 //# sourceMappingURL=index.d.mts.map