av6-pdf-engine 2.0.0 → 3.0.0

package/dist/index.d.ts

@@ -1,5 +1,29 @@
 import PDFDocument from 'pdfkit';
 
+type ShapeType = "rect" | "roundedRect" | "circle" | "ellipse" | "line" | "polygon" | "path";
+interface ShapePoint {
+    x: number;
+    y: number;
+}
+interface ShapeBlock extends BaseBlock {
+    type: "shape";
+    shape: ShapeType;
+    width?: number;
+    height?: number;
+    radius?: number;
+    points?: ShapePoint[];
+    path?: string;
+    fillColor?: string;
+    strokeColor?: string;
+    lineWidth?: number;
+    opacity?: number;
+    align?: Alignment;
+    marginTop?: number;
+    marginBottom?: number;
+    marginLeft?: number;
+    marginRight?: number;
+}
+
 interface SignatureBlock extends BaseBlock {
     type: "signature";
     height: number;
@@ -11,6 +35,39 @@ interface SignatureBlock extends BaseBlock {
     marginRight?: number;
 }
 
+type ListStyle = "bullet" | "number";
+interface ListItem {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    link?: string;
+    color?: string;
+    fontSize?: number;
+    font?: FontName;
+    lineGap?: number;
+    style?: StyleRef;
+}
+interface ListBlock extends BaseBlock {
+    type: "list";
+    items: (string | ListItem)[];
+    listStyle?: ListStyle;
+    bullet?: string;
+    start?: number;
+    markerWidth?: number;
+    markerGap?: number;
+    itemGap?: number;
+    fontSize?: number;
+    lineGap?: number;
+    color?: string;
+    style?: StyleRef;
+    marginTop?: number;
+    marginBottom?: number;
+    marginLeft?: number;
+    marginRight?: number;
+}
+
 interface KeyValueItem {
     key: string;
     value: string;
@@ -190,6 +247,8 @@ interface TextBlock extends BaseBlock {
     color?: string;
     font?: FontName;
     style?: StyleRef;
+    marginTop?: number;
+    marginBottom?: number;
     marginLeft?: number;
     marginRight?: number;
 }
@@ -200,16 +259,7 @@ type Orientation = "horizontal" | "vertical";
 type Width = number | "*";
 type InlineTextStyle = Omit<TextBlock, "type" | "text" | "style">;
 type BuiltInFont = "Helvetica" | "Helvetica-Bold" | "Helvetica-Oblique" | "Helvetica-BoldOblique" | "Times-Roman" | "Times-Bold" | "Times-Italic" | "Times-BoldItalic" | "Courier" | "Courier-Bold" | "Courier-Oblique" | "Courier-BoldOblique";
-/**
- * FontName:
- *  - autocomplete for built-ins
- *  - but still allows any custom string when you registerFont
- */
 type FontName = BuiltInFont | (string & {});
-/**
- * Style definition similar to pdfmake's style object.
- * Can be applied to text blocks and table cells.
- */
 interface StyleDef {
     italic?: boolean;
     underline?: boolean;
@@ -223,14 +273,8 @@ interface StyleDef {
     fillColor?: string;
     font?: FontName;
 }
-/** Shared style reference field (single or multiple style names). */
 type StyleRef = string | string[] | undefined;
 interface PageMargins {
-    /**
-     * TOP is treated as header band height.
-     * BOTTOM is treated as footer band height.
-     * LEFT/RIGHT are used for content only.
-     */
     top: number;
     right: number;
     bottom: number;
@@ -246,20 +290,24 @@ interface WatermarkDef {
     mode?: WatermarkMode;
 }
 interface PageBackgroundDef {
-    /** Path or Buffer for the image to be used as full-page background */
     src?: string | Buffer;
-    /** Optional global opacity for background (0–1). Default: 1 */
     opacity?: number;
 }
 interface FontRegistration {
     name: FontName;
     src: string | Buffer;
 }
+interface BoxSpacing {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+type SpacingInput = number | BoxSpacing;
 interface CustomDocDefinition {
-    pageSize?: string;
+    pageSize?: string | [number, number];
     margins: PageMargins;
     pageOrientation?: "portrait" | "landscape";
-    /** Optional font registrations (custom TTF/OTF) */
     fonts?: FontRegistration[];
     header?: HeaderDef;
     pageBackground?: PageBackgroundDef;
@@ -267,28 +315,41 @@ interface CustomDocDefinition {
     content: Block[];
     styles?: Record<string, StyleDef>;
     footer?: FooterInput;
-    /** Fallback image used when an image src fails to load or render. */
     defaultImage?: string | Buffer;
 }
 interface HeaderDef {
-    blocks: Block[];
+    blocks?: Block[];
+    backgroundBlocks?: Block[];
     visible?: boolean;
     marginTop?: number;
     marginBottom?: number;
     marginLeft?: number;
     marginRight?: number;
+    padding?: SpacingInput;
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
     backgroundColor?: string;
     backgroundImage?: string | Buffer;
+    backgroundOpacity?: number;
 }
 interface FooterDef {
     blocks: Block[];
+    backgroundBlocks?: Block[];
     visible?: boolean;
     marginTop?: number;
     marginBottom?: number;
     marginLeft?: number;
     marginRight?: number;
+    padding?: SpacingInput;
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
     backgroundColor?: string;
     backgroundImage?: string | Buffer;
+    backgroundOpacity?: number;
 }
 type FooterInput = FooterDef | Block | Block[] | ((pageNumber: number, pageSize: {
     width: number;
@@ -299,8 +360,14 @@ interface BaseBlock {
     backgroundColor?: string;
     backgroundImage?: string | Buffer;
     backgroundOpacity?: number;
+    backgroundBlocks?: Block[];
+    padding?: SpacingInput;
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
 }
-type Block = TextBlock | ImageBlock | QrCodeBlock | BarcodeBlock | LineBlock | ColumnsBlock | TableBlock | PageBreakBlock | KeyValueGridBlock | SignatureBlock;
+type Block = TextBlock | ImageBlock | QrCodeBlock | BarcodeBlock | LineBlock | ColumnsBlock | TableBlock | PageBreakBlock | KeyValueGridBlock | ListBlock | SignatureBlock | ShapeBlock;
 
 type BarcodeType = "CODE128" | "EAN13" | "CODE39" | "ITF" | "CODE93";
 declare const BARCODE_TYPES: Record<BarcodeType, BarcodeType>;
@@ -333,11 +400,18 @@ interface PageContext {
     signaturePlaced: boolean;
     afterSignature: boolean;
     inFooter: boolean;
+    /** True while finishPage is executing doc.addPage(), so the pageAdded listener can skip drawing the header (we draw it manually via startNewPageLayout). */
+    inManualPageAdd: boolean;
 }
 interface RenderEnv {
     marginLeft: number;
     innerWidth: number;
     allowPageBreak: boolean;
+    /**
+     * Internal flag.
+     * Used while rendering backgroundBlocks.
+     */
+    isBackgroundLayer?: boolean;
 }
 
 declare enum PdfEngineErrorCode {
@@ -390,4 +464,152 @@ declare const images: {
 declare function renderCustomPdf(def: CustomDocDefinition, outputPath: string): Promise<void>;
 declare function renderCustomPdfToBuffer(def: CustomDocDefinition): Promise<Buffer>;
 
-export { type Alignment, BARCODE_TYPES, type BarcodeBlock, type BarcodeType, type BaseBlock, type Block, type BuiltInFont, type ColumnsBlock, type CustomDocDefinition, type FontName, type FontRegistration, type FooterDef, type FooterInput, type HeaderDef, type ImageBlock, type InlineTextStyle, type KeyValueGridBlock, type KeyValueItem, type LineBlock, type Orientation, type PDFDoc, type PageBackgroundDef, type PageBreakBlock, type PageContext, type PageMargins, PdfEngineError, PdfEngineErrorCode, type PlacedCell, type QRErrorLevel, QR_ERROR_LEVEL, type QrCodeBlock, type RenderEnv, type SignatureBlock, type StyleDef, type StyleRef, type TableBlock, type TableBodyIterable, type TableBorderSide, type TableBorderStyle, type TableCell, type TableCellBorder, type TableColumnStyle, type TableRowStyle, type TextBlock, type WatermarkDef, type WatermarkMode, type Width, images, isPdfEngineError, renderCustomPdf, renderCustomPdfToBuffer, toPdfEngineError };
+type MeasureBlockHeightFn = (block: Block, env: RenderEnv) => number;
+declare function createMeasureBlockHeight(deps: {
+    doc: PDFDoc;
+    styles: Record<string, StyleDef>;
+    computeColumnPixelWidths: (widths: (number | "*")[], totalWidth: number) => number[];
+}): MeasureBlockHeightFn;
+
+interface BlockRendererDeps {
+    doc: PDFDoc;
+    ctx: PageContext;
+    styles: Record<string, StyleDef>;
+    computeColumnPixelWidths: (widths: (number | "*")[], totalWidth: number) => number[];
+    finishPage: (addNewPage: boolean) => void;
+    processSignatureBlock: (block: SignatureBlock) => void;
+    defaultImage?: string | Buffer;
+}
+declare function createBlockRenderer(deps: BlockRendererDeps): {
+    renderBlock: (block: Block, y: number | null, env: RenderEnv) => number;
+    renderBlockArray: (blocks: Block[], startY: number, env: RenderEnv) => number;
+    measureBlockHeight: MeasureBlockHeightFn;
+};
+
+declare function createInitialContext(doc: PDFDoc): PageContext;
+
+type EnsureSpaceForFn = (heightNeeded: number, env: RenderEnv) => void;
+/**
+ * Creates the `ensureSpaceFor` helper:
+ * - warns when a block is taller than the full page content area (it will overflow regardless)
+ * - if current block doesn't fit in remaining space, calls `finishPage(true)`
+ */
+declare function createEnsureSpaceFor(ctx: PageContext, doc: PDFDoc, bottomLimitForContent: BottomLimitForContentFn, finishPage: (addNewPage: boolean) => void): EnsureSpaceForFn;
+
+declare const contentEnv: (doc: PDFDoc) => RenderEnv;
+
+type RenderBlockArrayFn = (blocks: Block[], startY: number, env: RenderEnv) => number;
+interface FinishPageParams {
+    addNewPage: boolean;
+    doc: PDFDoc;
+    def: CustomDocDefinition;
+    ctx: PageContext;
+    footerBandHeight: number;
+    renderBlockArray: RenderBlockArrayFn;
+    startNewPageLayout: () => void;
+}
+declare function finishPage({ addNewPage, doc, def, ctx, footerBandHeight, renderBlockArray, startNewPageLayout, }: FinishPageParams): void;
+
+declare function drawFooter(doc: PDFDoc, def: CustomDocDefinition, ctx: PageContext, footerBandHeight: number, renderBlockArray: (blocks: Block[], startY: number, env: RenderEnv) => number): void;
+
+declare function drawHeader(doc: PDFDoc, def: CustomDocDefinition, headerBandHeight: number, header: HeaderDef | undefined, renderBlockArray: (blocks: Block[], startY: number, env: RenderEnv) => number): void;
+
+declare function normalizeImageSrc(src: string | Buffer | undefined, fallback?: string | Buffer): Promise<string | Buffer | undefined>;
+declare function materializeImagesInBlocks(blocks: Block[], fallback?: string | Buffer): Promise<Block[]>;
+
+/**
+ * Compute pixel widths for a set of column width descriptors.
+ * - number: fixed width
+ * - "*": flex unit
+ */
+declare function computeColumnPixelWidths(widths: Width[], totalWidth: number): number[];
+
+/**
+ * Draws a full-page background image with optional opacity.
+ */
+declare function drawPageBackground(doc: PDFDoc, pageBackground?: PageBackgroundDef): void;
+
+declare function getBottomLimitForContent(doc: PDFDoc, ctx: PageContext): number;
+
+type BottomLimitForContentFn = () => number;
+/**
+ * Creates a function that returns the current "bottom limit"
+ * for content on a page (taking signature reservation into account).
+ */
+declare function createBottomLimitForContent(doc: PDFDoc, ctx: PageContext): BottomLimitForContentFn;
+
+declare function generateQrBuffer(value: string, size: number, version?: number, errorCorrectionLevel?: "L" | "M" | "Q" | "H"): Promise<Buffer>;
+declare function mapBarcodeTypeToBcid(bcType?: BarcodeType | null): string;
+declare function generateBarcodeBuffer(value: string, options?: {
+    bcType?: BarcodeType;
+    scale?: number;
+    barHeight?: number;
+    includetext?: boolean;
+    textalign?: "left" | "center" | "right";
+}): Promise<Buffer>;
+declare function materializeQrAndBarcodesInBlocks(blocks: Block[]): Promise<Block[]>;
+
+declare function drawSignatureBlock(doc: PDFDoc, block: SignatureBlock, y: number, env: RenderEnv, renderBlockArray: (blocks: Block[], startY: number, env: RenderEnv) => number): void;
+/** Dependencies for the signature reservation logic */
+interface SignatureProcessorDeps {
+    doc: PDFDoc;
+    ctx: PageContext;
+    styles: Record<string, StyleDef>;
+    /** Called to finish current page and optionally start a new one */
+    finishPage: (addNewPage: boolean) => void;
+    /** Returns the base RenderEnv for content for the current page */
+    contentEnvFn: (doc: PDFDoc) => RenderEnv;
+}
+/**
+ * Creates the `processSignatureBlock` function used in the main renderer.
+ * It measures inner content, reserves space at the bottom of the page,
+ * and updates `ctx.signature*` fields.
+ */
+declare function createProcessSignatureBlock({ doc, ctx, styles, finishPage, contentEnvFn }: SignatureProcessorDeps): (block: SignatureBlock) => void;
+
+interface ResolvedSpacing {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+declare const resolveSpacing: (value?: SpacingInput, overrides?: BoxSpacing) => ResolvedSpacing;
+declare const resolveBlockPadding: (block: BaseBlock) => ResolvedSpacing;
+declare const resolveHeaderPadding: (header: HeaderDef) => ResolvedSpacing;
+declare const resolveFooterPadding: (footer: FooterDef) => ResolvedSpacing;
+declare const hasPadding: (padding: ResolvedSpacing) => boolean;
+
+interface StartPageLayoutDeps {
+    doc: PDFDoc;
+    def: CustomDocDefinition;
+    ctx: PageContext;
+    headerBandHeight: number;
+    renderBlockArray: RenderBlockArrayFn;
+}
+/**
+ * Returns the `startNewPageLayout` function used in the main renderer.
+ * It:
+ *  - draws page background
+ *  - draws header
+ *  - (if mode is not "last"/"firstLast"/etc) draws watermark
+ *  - resets `ctx` per new page
+ */
+declare function createStartNewPageLayout({ doc, def, ctx, headerBandHeight, renderBlockArray }: StartPageLayoutDeps): () => void;
+
+declare function mergeStyleDefs(styles: Record<string, StyleDef> | undefined, names: StyleRef): StyleDef;
+declare function resolveTextBlock(styles: Record<string, StyleDef> | undefined, block: TextBlock): TextBlock;
+declare function resolveTableCell(styles: Record<string, StyleDef> | undefined, cell: TableCell): TableCell;
+declare const getFontNameForText: (tb: TextBlock) => FontName;
+declare const drawStyledText: (doc: PDFDoc, tb: TextBlock, x: number, y: number, width: number) => void;
+
+/**
+ * Returns true if the watermark mode requires knowledge of the last page.
+ */
+declare function watermarkUsesLast(mode?: WatermarkMode): boolean;
+/**
+ * Draw watermark text for a given page.
+ * This is extracted so the same logic can be reused from multiple places.
+ */
+declare function drawWatermarkForPage(doc: PDFDoc, watermark: WatermarkDef, pageNumber: number, isLast: boolean): void;
+
+export { type Alignment, BARCODE_TYPES, type BarcodeBlock, type BarcodeType, type BaseBlock, type Block, type BlockRendererDeps, type BottomLimitForContentFn, type BoxSpacing, type BuiltInFont, type ColumnsBlock, type CustomDocDefinition, type EnsureSpaceForFn, type FinishPageParams, type FontName, type FontRegistration, type FooterDef, type FooterInput, type HeaderDef, type ImageBlock, type InlineTextStyle, type KeyValueGridBlock, type KeyValueItem, type LineBlock, type ListBlock, type ListItem, type ListStyle, type MeasureBlockHeightFn, type Orientation, type PDFDoc, type PageBackgroundDef, type PageBreakBlock, type PageContext, type PageMargins, PdfEngineError, PdfEngineErrorCode, type PlacedCell, type QRErrorLevel, QR_ERROR_LEVEL, type QrCodeBlock, type RenderBlockArrayFn, type RenderEnv, type ResolvedSpacing, type ShapeBlock, type ShapePoint, type ShapeType, type SignatureBlock, type SpacingInput, type StyleDef, type StyleRef, type TableBlock, type TableBodyIterable, type TableBorderSide, type TableBorderStyle, type TableCell, type TableCellBorder, type TableColumnStyle, type TableRowStyle, type TextBlock, type WatermarkDef, type WatermarkMode, type Width, computeColumnPixelWidths, contentEnv, createBlockRenderer, createBottomLimitForContent, createEnsureSpaceFor, createInitialContext, createMeasureBlockHeight, createProcessSignatureBlock, createStartNewPageLayout, drawFooter, drawHeader, drawPageBackground, drawSignatureBlock, drawStyledText, drawWatermarkForPage, finishPage, generateBarcodeBuffer, generateQrBuffer, getBottomLimitForContent, getFontNameForText, hasPadding, images, isPdfEngineError, mapBarcodeTypeToBcid, materializeImagesInBlocks, materializeQrAndBarcodesInBlocks, mergeStyleDefs, normalizeImageSrc, renderCustomPdf, renderCustomPdfToBuffer, resolveBlockPadding, resolveFooterPadding, resolveHeaderPadding, resolveSpacing, resolveTableCell, resolveTextBlock, toPdfEngineError, watermarkUsesLast };