jspdf-md-renderer 3.5.1 → 4.0.0

package/README.md

@@ -2,6 +2,15 @@
 
 A jsPDF utility to render Markdown directly into formatted PDFs with custom designs.
 
+## What's New in v4
+
+- Unified inline layout engine for consistent wrapping/alignment.
+- Safe wrapping for long unbroken tokens (long URLs, long inline code).
+- Heading scale controls (`heading.h1` ... `heading.h6`).
+- Task list support (`- [x]` / `- [ ]`).
+- Header/footer + page numbers.
+- Spacing system (`spacing.*`) and richer style options (`codeBlock`, `blockquote`, `list`, `paragraph`).
+
 [![npm version](https://img.shields.io/npm/v/jspdf-md-renderer.svg)](https://www.npmjs.com/package/jspdf-md-renderer)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Downloads](https://img.shields.io/npm/dm/jspdf-md-renderer.svg)](https://www.npmjs.com/package/jspdf-md-renderer)
@@ -113,6 +122,25 @@ const generatePDF = async () => {
             regular: { name: 'helvetica', style: 'normal' },
             light: { name: 'helvetica', style: 'light' },
         },
+        heading: {
+            h1: 24,
+            h2: 20,
+            h3: 17,
+            h4: 15,
+            h5: 13,
+            h6: 12,
+            color: '#1A365D',
+        },
+        spacing: {
+            afterParagraph: 4,
+            afterHeading: 2,
+            afterCodeBlock: 4,
+            betweenListItems: 1,
+        },
+        footer: {
+            showPageNumbers: true,
+            align: 'right',
+        },
         endCursorYHandler: (y) => {
             console.log('End cursor Y position:', y);
         },
@@ -262,6 +290,38 @@ The following Markdown elements are currently supported by `jspdf-md-renderer`:
     | Row 2    | Data     | Value    |
     ```
 
+## New Options (v4 quick reference)
+
+```ts
+const options = {
+  heading: { h1: 26, h2: 22, h3: 18, bottomSpacing: 3 },
+  list: { bulletChar: '• ', indentSize: 8, itemSpacing: 0 },
+  paragraph: { bottomSpacing: 3, color: '#111827' },
+  blockquote: { barColor: '#4A90D9', barWidth: 2, paddingLeft: 6 },
+  codeBlock: {
+    backgroundColor: '#F6F8FA',
+    borderColor: '#E1E4E8',
+    borderRadius: 3,
+    padding: 5,
+    showLanguageLabel: true,
+    textColor: '#111827',
+  },
+  spacing: {
+    afterHeading: 2,
+    afterParagraph: 4,
+    afterCodeBlock: 4,
+    afterBlockquote: 3,
+    afterImage: 2,
+    afterHR: 2,
+    betweenListItems: 0,
+    afterList: 3,
+    afterTable: 3,
+  },
+  header: { text: 'My Report', align: 'center', color: '#6b7280', fontSize: 9 },
+  footer: { showPageNumbers: true, align: 'right' },
+}
+```
+
 ## Examples
 
 You can explore complete rendered examples in the documentation site:

package/dist/index.d.mts

@@ -35,7 +35,7 @@ type RenderOption = {
   };
   page: {
     format?: string | number[];
-    unit?: jsPDFOptions['unit'];
+    unit: jsPDFOptions['unit'];
     orientation?: jsPDFOptions['orientation'];
     maxContentWidth: number;
     maxContentHeight: number;
@@ -54,6 +54,38 @@ type RenderOption = {
     light: FontItem;
     code?: FontItem;
   };
+  heading?: {
+    /** Font size for h1-h6. Values are absolute (e.g. 22, 20, 18, 16, 14, 12). */h1?: number;
+    h2?: number;
+    h3?: number;
+    h4?: number;
+    h5?: number;
+    h6?: number; /** Space below heading before next element, in doc units. Default: 2 */
+    bottomSpacing?: number; /** Text color for all headings as hex. Default: '#000000' */
+    color?: string;
+    h1Color?: string;
+    h2Color?: string;
+    h3Color?: string;
+    h4Color?: string;
+    h5Color?: string;
+    h6Color?: string;
+  };
+  list?: {
+    /** Bullet character for unordered lists. Default: '\u2022 ' */bulletChar?: string; /** Extra indent per nesting level in doc units. Default: uses page.indent */
+    indentSize?: number; /** Vertical space between list items. Default: 0 */
+    itemSpacing?: number;
+  };
+  paragraph?: {
+    /** Space below each paragraph in doc units. Default: lineSpace */bottomSpacing?: number; /** Text color for paragraph text as hex. Default: '#000000' */
+    color?: string;
+  };
+  blockquote?: {
+    /** Left bar color as hex. Default: '#AAAAAA' */barColor?: string; /** Left bar width in doc units. Default: 1 */
+    barWidth?: number; /** Left padding from bar to text in doc units. Default: 4 */
+    paddingLeft?: number; /** Background color as hex. Default: undefined (transparent) */
+    backgroundColor?: string; /** Space below blockquote before next element, in doc units. Default: lineSpace */
+    bottomSpacing?: number;
+  };
   content?: {
     textAlignment: 'left' | 'right' | 'center' | 'justify';
   };
@@ -70,9 +102,49 @@ type RenderOption = {
   image?: {
     /** Default alignment for images: 'left' | 'center' | 'right'. Default: 'left' */defaultAlign?: 'left' | 'center' | 'right';
   };
+  codeBlock?: {
+    backgroundColor?: string;
+    borderColor?: string;
+    borderRadius?: number;
+    padding?: number;
+    fontSizeScale?: number; /** Whether to show language label. Default: true */
+    showLanguageLabel?: boolean; /** Text color for code content as hex. Default: '#000000' */
+    textColor?: string; /** Language label color as hex. Default: '#666666' */
+    labelColor?: string;
+  };
+  spacing?: {
+    /** Space below headings in doc units. Default: 2 */afterHeading?: number; /** Space below paragraphs in doc units. Default: 3 */
+    afterParagraph?: number; /** Space below code blocks in doc units. Default: 3 */
+    afterCodeBlock?: number; /** Space below blockquotes in doc units. Default: 3 */
+    afterBlockquote?: number; /** Space below images in doc units. Default: 2 */
+    afterImage?: number; /** Space below horizontal rules in doc units. Default: 2 */
+    afterHR?: number; /** Space between list items in doc units. Default: 0 */
+    betweenListItems?: number; /** Space below a complete list in doc units. Default: 3 */
+    afterList?: number; /** Space below tables in doc units. Default: 3 */
+    afterTable?: number;
+  };
+  header?: {
+    /** Text to render in header area of each page */text?: string | ((pageNumber: number, totalPages: number) => string); /** Y position of header text from top in doc units. Default: 5 */
+    y?: number; /** Font size for header text. Default: 9 */
+    fontSize?: number; /** Text color for header. Default: '#666666' */
+    color?: string; /** Alignment of header text. Default: 'center' */
+    align?: 'left' | 'center' | 'right';
+  };
+  footer?: {
+    /** Text to render in footer area of each page */text?: string | ((pageNumber: number, totalPages: number) => string); /** Y position from top of page in doc units. Default: pageHeight - 5 */
+    y?: number; /** Font size for footer text. Default: 9 */
+    fontSize?: number; /** Text color for footer. Default: '#666666' */
+    color?: string; /** Alignment of footer text. Default: 'right' */
+    align?: 'right' | 'left' | 'center'; /** Shortcut: render page numbers with format "Page X of Y" */
+    showPageNumbers?: boolean;
+  };
   pageBreakHandler?: (doc: jsPDF) => void;
   endCursorYHandler: (y: number) => void;
 };
+type Cursor = {
+  x: number;
+  y: number;
+};
 type FontItem = {
   name: string;
   style: string;
@@ -109,7 +181,9 @@ type ParsedElement = {
   height?: number;
   align?: 'left' | 'center' | 'right';
   naturalWidth?: number;
-  naturalHeight?: number;
+  naturalHeight?: number; /** Whether this list item is a task (checkbox) item */
+  task?: boolean; /** Whether the task checkbox is checked */
+  checked?: boolean;
 };
 //#endregion
 //#region src/parser/MdTextParser.d.ts
@@ -121,4 +195,141 @@ type ParsedElement = {
  */
 declare const MdTextParser: (text: string) => Promise<ParsedElement[]>;
 //#endregion
-export { MdTextParser, MdTextRender, type RenderOption };
+//#region src/types/styledWordInfo.d.ts
+/**
+ * Enhanced word info types for styled text justification.
+ * These types allow tracking font styles per word for proper justified rendering.
+ */
+type TextStyle = 'normal' | 'bold' | 'italic' | 'bolditalic' | 'codespan';
+/**
+ * Information about a single styled word for justified text rendering.
+ */
+interface StyledWordInfo {
+  /** The word text */
+  text: string;
+  /** Measured width in PDF points */
+  width: number;
+  /** Font style to apply when rendering */
+  style: TextStyle;
+  /** Whether this word is part of a link */
+  isLink?: boolean;
+  /** URL if this is a link */
+  href?: string;
+  /** Optional link color override */
+  linkColor?: number[];
+  /** Whether this is an inline image */
+  isImage?: boolean;
+  /** The image parsed element */
+  imageElement?: ParsedElement;
+  /** The height of the image to reserve */
+  imageHeight?: number;
+  /** Marks a hard line break */
+  isBr?: boolean;
+  /** Whether this word was followed by whitespace in the source Markdown */
+  hasTrailingSpace?: boolean;
+}
+/**
+ * Represents a line of styled words for justified rendering.
+ */
+interface StyledLine {
+  /** Words in this line */
+  words: StyledWordInfo[];
+  /** Sum of word widths (without inter-word spacing) */
+  totalTextWidth: number;
+  /** Last line of paragraph shouldn't be fully justified */
+  isLastLine: boolean;
+  /** Line height (max of text height and inline image heights) */
+  lineHeight: number;
+}
+//#endregion
+//#region src/store/renderStore.d.ts
+declare class RenderStore {
+  private cursor;
+  private lastContentY_;
+  private options_;
+  private inlineLock;
+  constructor(options: RenderOption);
+  getCursor(): Cursor;
+  setCursor(newCursor: Cursor): void;
+  get options(): RenderOption;
+  get isInlineLockActive(): boolean;
+  activateInlineLock(): void;
+  deactivateInlineLock(): void;
+  /**
+   * Updates the x pointer of the cursor.
+   * @param value The value to set or add.
+   * @param operation 'set' to assign a new value, 'add' to increment the current value.
+   * @default operation = 'set'
+   */
+  updateX(value: number, operation?: 'set' | 'add'): void;
+  /**
+   * Updates the y pointer of the cursor.
+   * @param value The value to set or add.
+   * @param operation 'set' to assign a new value, 'add' to increment the current value.
+   * @default operation = 'set'
+   */
+  updateY(value: number, operation?: 'set' | 'add'): void;
+  /**
+   * Records a Y position as the bottom of rendered content.
+   * This is useful for container components (like blockquotes) to know
+   * where their actual text content ends, ignoring any trailing margins.
+   * @param specificY Optional Y value to record. Defaults to current cursor Y.
+   */
+  recordContentY(specificY?: number): void;
+  /**
+   * Gets the last Y position recorded as content bottom.
+   */
+  get lastContentY(): number;
+  get X(): number;
+  get Y(): number;
+}
+//#endregion
+//#region src/layout/layoutEngine.d.ts
+interface LayoutOptions {
+  alignment?: 'left' | 'right' | 'center' | 'justify';
+  /** When true, the last line advances Y by only the raw text height
+   *  (no trailing inter-line spacing), so the caller's explicit
+   *  bottomSpacing is the sole gap after the block. */
+  trimLastLine?: boolean;
+}
+/**
+ * THE single entry point for rendering any mixed inline content.
+ * All paragraph, heading, list item, and blockquote text must go through here.
+ *
+ * Handles: word splitting, line breaking, page breaks, styled rendering.
+ * Returns the final Y position after rendering.
+ */
+declare const renderInlineContent: (doc: jsPDF, elements: ParsedElement[], x: number, y: number, maxWidth: number, store: RenderStore, opts?: LayoutOptions) => number;
+/**
+ * Render a single string of plain (unstyled) text with wrapping and page breaks.
+ * Use this for simple text in list items and raw items where there are no inline styles.
+ */
+declare const renderPlainText: (doc: jsPDF, text: string, x: number, y: number, maxWidth: number, store: RenderStore, opts?: LayoutOptions) => number;
+//#endregion
+//#region src/enums/mdTokenType.d.ts
+declare enum MdTokenType {
+  Heading = "heading",
+  Paragraph = "paragraph",
+  List = "list",
+  ListItem = "list_item",
+  Blockquote = "blockquote",
+  Code = "code",
+  CodeSpan = "codespan",
+  Table = "table",
+  Html = "html",
+  Hr = "hr",
+  Image = "image",
+  Link = "link",
+  Strong = "strong",
+  Em = "em",
+  TableHeader = "table_header",
+  TableCell = "table_cell",
+  Raw = "raw",
+  Text = "text",
+  Br = "br"
+}
+//#endregion
+//#region src/utils/options-validation.d.ts
+declare const validateOptions: (options: RenderOption) => RenderOption;
+//#endregion
+export { MdTextParser, MdTextRender, MdTokenType, type ParsedElement, type RenderOption, type StyledLine, type StyledWordInfo, type TextStyle, renderInlineContent, renderPlainText, validateOptions };

package/dist/index.d.ts

@@ -35,7 +35,7 @@ type RenderOption = {
   };
   page: {
     format?: string | number[];
-    unit?: jsPDFOptions['unit'];
+    unit: jsPDFOptions['unit'];
     orientation?: jsPDFOptions['orientation'];
     maxContentWidth: number;
     maxContentHeight: number;
@@ -54,6 +54,38 @@ type RenderOption = {
     light: FontItem;
     code?: FontItem;
   };
+  heading?: {
+    /** Font size for h1-h6. Values are absolute (e.g. 22, 20, 18, 16, 14, 12). */h1?: number;
+    h2?: number;
+    h3?: number;
+    h4?: number;
+    h5?: number;
+    h6?: number; /** Space below heading before next element, in doc units. Default: 2 */
+    bottomSpacing?: number; /** Text color for all headings as hex. Default: '#000000' */
+    color?: string;
+    h1Color?: string;
+    h2Color?: string;
+    h3Color?: string;
+    h4Color?: string;
+    h5Color?: string;
+    h6Color?: string;
+  };
+  list?: {
+    /** Bullet character for unordered lists. Default: '\u2022 ' */bulletChar?: string; /** Extra indent per nesting level in doc units. Default: uses page.indent */
+    indentSize?: number; /** Vertical space between list items. Default: 0 */
+    itemSpacing?: number;
+  };
+  paragraph?: {
+    /** Space below each paragraph in doc units. Default: lineSpace */bottomSpacing?: number; /** Text color for paragraph text as hex. Default: '#000000' */
+    color?: string;
+  };
+  blockquote?: {
+    /** Left bar color as hex. Default: '#AAAAAA' */barColor?: string; /** Left bar width in doc units. Default: 1 */
+    barWidth?: number; /** Left padding from bar to text in doc units. Default: 4 */
+    paddingLeft?: number; /** Background color as hex. Default: undefined (transparent) */
+    backgroundColor?: string; /** Space below blockquote before next element, in doc units. Default: lineSpace */
+    bottomSpacing?: number;
+  };
   content?: {
     textAlignment: 'left' | 'right' | 'center' | 'justify';
   };
@@ -70,9 +102,49 @@ type RenderOption = {
   image?: {
     /** Default alignment for images: 'left' | 'center' | 'right'. Default: 'left' */defaultAlign?: 'left' | 'center' | 'right';
   };
+  codeBlock?: {
+    backgroundColor?: string;
+    borderColor?: string;
+    borderRadius?: number;
+    padding?: number;
+    fontSizeScale?: number; /** Whether to show language label. Default: true */
+    showLanguageLabel?: boolean; /** Text color for code content as hex. Default: '#000000' */
+    textColor?: string; /** Language label color as hex. Default: '#666666' */
+    labelColor?: string;
+  };
+  spacing?: {
+    /** Space below headings in doc units. Default: 2 */afterHeading?: number; /** Space below paragraphs in doc units. Default: 3 */
+    afterParagraph?: number; /** Space below code blocks in doc units. Default: 3 */
+    afterCodeBlock?: number; /** Space below blockquotes in doc units. Default: 3 */
+    afterBlockquote?: number; /** Space below images in doc units. Default: 2 */
+    afterImage?: number; /** Space below horizontal rules in doc units. Default: 2 */
+    afterHR?: number; /** Space between list items in doc units. Default: 0 */
+    betweenListItems?: number; /** Space below a complete list in doc units. Default: 3 */
+    afterList?: number; /** Space below tables in doc units. Default: 3 */
+    afterTable?: number;
+  };
+  header?: {
+    /** Text to render in header area of each page */text?: string | ((pageNumber: number, totalPages: number) => string); /** Y position of header text from top in doc units. Default: 5 */
+    y?: number; /** Font size for header text. Default: 9 */
+    fontSize?: number; /** Text color for header. Default: '#666666' */
+    color?: string; /** Alignment of header text. Default: 'center' */
+    align?: 'left' | 'center' | 'right';
+  };
+  footer?: {
+    /** Text to render in footer area of each page */text?: string | ((pageNumber: number, totalPages: number) => string); /** Y position from top of page in doc units. Default: pageHeight - 5 */
+    y?: number; /** Font size for footer text. Default: 9 */
+    fontSize?: number; /** Text color for footer. Default: '#666666' */
+    color?: string; /** Alignment of footer text. Default: 'right' */
+    align?: 'right' | 'left' | 'center'; /** Shortcut: render page numbers with format "Page X of Y" */
+    showPageNumbers?: boolean;
+  };
   pageBreakHandler?: (doc: jsPDF) => void;
   endCursorYHandler: (y: number) => void;
 };
+type Cursor = {
+  x: number;
+  y: number;
+};
 type FontItem = {
   name: string;
   style: string;
@@ -109,7 +181,9 @@ type ParsedElement = {
   height?: number;
   align?: 'left' | 'center' | 'right';
   naturalWidth?: number;
-  naturalHeight?: number;
+  naturalHeight?: number; /** Whether this list item is a task (checkbox) item */
+  task?: boolean; /** Whether the task checkbox is checked */
+  checked?: boolean;
 };
 //#endregion
 //#region src/parser/MdTextParser.d.ts
@@ -121,4 +195,141 @@ type ParsedElement = {
  */
 declare const MdTextParser: (text: string) => Promise<ParsedElement[]>;
 //#endregion
-export { MdTextParser, MdTextRender, type RenderOption };
+//#region src/types/styledWordInfo.d.ts
+/**
+ * Enhanced word info types for styled text justification.
+ * These types allow tracking font styles per word for proper justified rendering.
+ */
+type TextStyle = 'normal' | 'bold' | 'italic' | 'bolditalic' | 'codespan';
+/**
+ * Information about a single styled word for justified text rendering.
+ */
+interface StyledWordInfo {
+  /** The word text */
+  text: string;
+  /** Measured width in PDF points */
+  width: number;
+  /** Font style to apply when rendering */
+  style: TextStyle;
+  /** Whether this word is part of a link */
+  isLink?: boolean;
+  /** URL if this is a link */
+  href?: string;
+  /** Optional link color override */
+  linkColor?: number[];
+  /** Whether this is an inline image */
+  isImage?: boolean;
+  /** The image parsed element */
+  imageElement?: ParsedElement;
+  /** The height of the image to reserve */
+  imageHeight?: number;
+  /** Marks a hard line break */
+  isBr?: boolean;
+  /** Whether this word was followed by whitespace in the source Markdown */
+  hasTrailingSpace?: boolean;
+}
+/**
+ * Represents a line of styled words for justified rendering.
+ */
+interface StyledLine {
+  /** Words in this line */
+  words: StyledWordInfo[];
+  /** Sum of word widths (without inter-word spacing) */
+  totalTextWidth: number;
+  /** Last line of paragraph shouldn't be fully justified */
+  isLastLine: boolean;
+  /** Line height (max of text height and inline image heights) */
+  lineHeight: number;
+}
+//#endregion
+//#region src/store/renderStore.d.ts
+declare class RenderStore {
+  private cursor;
+  private lastContentY_;
+  private options_;
+  private inlineLock;
+  constructor(options: RenderOption);
+  getCursor(): Cursor;
+  setCursor(newCursor: Cursor): void;
+  get options(): RenderOption;
+  get isInlineLockActive(): boolean;
+  activateInlineLock(): void;
+  deactivateInlineLock(): void;
+  /**
+   * Updates the x pointer of the cursor.
+   * @param value The value to set or add.
+   * @param operation 'set' to assign a new value, 'add' to increment the current value.
+   * @default operation = 'set'
+   */
+  updateX(value: number, operation?: 'set' | 'add'): void;
+  /**
+   * Updates the y pointer of the cursor.
+   * @param value The value to set or add.
+   * @param operation 'set' to assign a new value, 'add' to increment the current value.
+   * @default operation = 'set'
+   */
+  updateY(value: number, operation?: 'set' | 'add'): void;
+  /**
+   * Records a Y position as the bottom of rendered content.
+   * This is useful for container components (like blockquotes) to know
+   * where their actual text content ends, ignoring any trailing margins.
+   * @param specificY Optional Y value to record. Defaults to current cursor Y.
+   */
+  recordContentY(specificY?: number): void;
+  /**
+   * Gets the last Y position recorded as content bottom.
+   */
+  get lastContentY(): number;
+  get X(): number;
+  get Y(): number;
+}
+//#endregion
+//#region src/layout/layoutEngine.d.ts
+interface LayoutOptions {
+  alignment?: 'left' | 'right' | 'center' | 'justify';
+  /** When true, the last line advances Y by only the raw text height
+   *  (no trailing inter-line spacing), so the caller's explicit
+   *  bottomSpacing is the sole gap after the block. */
+  trimLastLine?: boolean;
+}
+/**
+ * THE single entry point for rendering any mixed inline content.
+ * All paragraph, heading, list item, and blockquote text must go through here.
+ *
+ * Handles: word splitting, line breaking, page breaks, styled rendering.
+ * Returns the final Y position after rendering.
+ */
+declare const renderInlineContent: (doc: jsPDF, elements: ParsedElement[], x: number, y: number, maxWidth: number, store: RenderStore, opts?: LayoutOptions) => number;
+/**
+ * Render a single string of plain (unstyled) text with wrapping and page breaks.
+ * Use this for simple text in list items and raw items where there are no inline styles.
+ */
+declare const renderPlainText: (doc: jsPDF, text: string, x: number, y: number, maxWidth: number, store: RenderStore, opts?: LayoutOptions) => number;
+//#endregion
+//#region src/enums/mdTokenType.d.ts
+declare enum MdTokenType {
+  Heading = "heading",
+  Paragraph = "paragraph",
+  List = "list",
+  ListItem = "list_item",
+  Blockquote = "blockquote",
+  Code = "code",
+  CodeSpan = "codespan",
+  Table = "table",
+  Html = "html",
+  Hr = "hr",
+  Image = "image",
+  Link = "link",
+  Strong = "strong",
+  Em = "em",
+  TableHeader = "table_header",
+  TableCell = "table_cell",
+  Raw = "raw",
+  Text = "text",
+  Br = "br"
+}
+//#endregion
+//#region src/utils/options-validation.d.ts
+declare const validateOptions: (options: RenderOption) => RenderOption;
+//#endregion
+export { MdTextParser, MdTextRender, MdTokenType, type ParsedElement, type RenderOption, type StyledLine, type StyledWordInfo, type TextStyle, renderInlineContent, renderPlainText, validateOptions };