jspdf-utils 0.1.25 → 0.1.27

package/README.md

@@ -1,6 +1,7 @@
 # jsPDF Utils
 
-HTML to PDF utilities for jsPDF with support for Arabic text, tables, and automatic page breaking.
+Utilities for rendering HTML into paginated PDF output with `jsPDF` and
+`html2canvas`.
 
 ## Installation
 
@@ -8,79 +9,137 @@ HTML to PDF utilities for jsPDF with support for Arabic text, tables, and automa
 npm install jspdf-utils jspdf html2canvas
 ```
 
-## Usage
+## Exported API
 
-```javascript
+- `generatePDF(doc, source, opts)`
+- `generateImagePDF(source, opts)`
+- `generateImages(source, opts)`
+- `previewImages(source, container, opts)`
+- `PAGE_SIZES`
+- `PAGE_MARGINS`
+- Types: `PageOptions`, `PageOptionsInput`, `ImagePDFOptions`
+
+Type import example:
+
+```ts
+import type { PageOptionsInput } from "jspdf-utils";
+```
+
+## Quick Start
+
+### 1) HTML -> vector/text PDF (`doc.html`)
+
+```ts
 import jsPDF from "jspdf";
-import { renderHTML } from "jspdf-utils";
+import { generatePDF } from "jspdf-utils";
+
+const target = document.getElementById("print-section");
+if (!target) throw new Error("Missing #print-section");
 
-const doc = new jsPDF({ unit: "mm", format: "a4" });
+const doc = new jsPDF({ unit: "mm" });
 
-// Add fonts if needed for Arabic/RTL text
-doc.addFont("path/to/arial.ttf", "arial", "normal", "normal");
-doc.addFont("path/to/arial-bold.ttf", "arial", "normal", "bold");
+// Optional for Arabic/RTL text:
+// doc.addFont("/fonts/arial.ttf", "arial", "normal");
+// doc.addFont("/fonts/arial-bold.ttf", "arial", "bold");
 
-// Render HTML element to PDF
-const element = document.getElementById("content");
-await renderHTML(doc, element);
+await generatePDF(doc, target, {
+  format: "a4",
+  margin: { top: 20, right: 20, bottom: 20, left: 20 },
+  forcedPageCount: 1,
+});
 
 doc.save("output.pdf");
 ```
 
-## Features
+### 2) HTML -> image-based PDF (raster pages)
 
-- **Automatic page breaking**: Prevents tables and text from being split awkwardly
-- **Table splitting**: Large tables are split across pages with repeated headers
-- **Text wrapping**: Long text blocks are intelligently broken at word boundaries
-- **RTL/Arabic support**: Works with right-to-left languages when proper fonts are loaded
+```ts
+import { generateImagePDF } from "jspdf-utils";
 
-## Development
+const target = document.getElementById("print-section");
+if (!target) throw new Error("Missing #print-section");
 
-### Running the Example
+const imagePDF = await generateImagePDF(target, {
+  format: "a5",
+  imageFormat: "PNG",
+  forcedPageCount: 1,
+});
 
-```bash
-npm install
-npm run dev
-# Open http://localhost:5173
+imagePDF.save("output-image.pdf");
 ```
 
-### Project Structure
+### 3) Preview pages as images in a container
 
+```ts
+import { previewImages } from "jspdf-utils";
+
+const target = document.getElementById("print-section");
+const preview = document.getElementById("preview-container");
+if (!target || !preview) throw new Error("Missing preview elements");
+
+await previewImages(target, preview, {
+  format: "a5",
+  forcedPageCount: 1,
+});
 ```
-├── src/
-│   └── html-to-pdf.js    # Main utility functions
-├── index.html             # Example/demo page
-└── package.json
-```
 
-## API
+## Options
+
+### `PageOptionsInput`
+
+- `unit?: string` (default: `"mm"`)
+- `format?: "a0" | "a1" | "a2" | "a3" | "a4" | "a5" | "a6" | "letter" | "legal" | "tabloid"` (default: `"a4"`)
+- `pageWidth?: number` (default comes from `format`)
+- `pageHeight?: number` (default comes from `format`)
+- `margin?: number | { top?: number; right?: number; bottom?: number; left?: number }`
+
+Important:
+
+- `generatePDF`, `generateImagePDF`, `generateImages`, and `previewImages` use
+  page sizing from their `opts` (`format` / `pageWidth` / `pageHeight`).
+- Do not rely on `new jsPDF({ format: ... })` to control layout in
+  `generatePDF`; pass `format` in `opts` instead.
+
+### `ImagePDFOptions`
+
+- `imageFormat?: "JPEG" | "PNG"`
+- `imageQuality?: number`
+- `scale?: number`
+- `marginContent?: MarginContentInput`
+- `forcedPageCount?: number`
 
-### `renderHTML(doc, source, opts)`
+`forcedPageCount` behavior:
 
-Renders an HTML element to PDF.
+- Forces output to the first `N` pages only.
+- `generatePDF`: trims extra pages after `doc.html` rendering.
+- `generateImagePDF`: only rasterizes and writes first `N` pages.
+- `generateImages` and `previewImages`: only returns/displays first `N` pages.
+- Invalid values (`<= 0`, `NaN`, `Infinity`) are ignored.
 
-- **doc**: jsPDF instance
-- **source**: HTML element to render
-- **opts**: Optional configuration (overrides defaults)
+## Margin Content and Borders
 
-### `prepare(source, opts)`
+`marginContent` supports:
 
-Prepares an HTML element for rendering (used internally by renderHTML).
+- `top`, `right`, `bottom`, `left` as:
+  - `HTMLElement`, or
+  - `(page: number, totalPages: number) => HTMLElement`
+- `contentBorder` (vector rectangle)
+- `textBorder` (repeated text around page edges)
 
-Returns: `{ clone, layout, options, cleanup }`
+Rendering order:
 
-### Default Options
+- Margin content and borders are rendered beneath page content.
+- Main document content stays visually above borders/text borders.
 
-```javascript
-{
-  unit: 'mm',
-  format: 'a4',
-  pageWidth: 210,
-  pageHeight: 297,
-  margin: { top: 20, right: 20, bottom: 20, left: 20 }
-}
+## Development
+
+```bash
+npm install
+npm run dev
 ```
 
+Open [http://localhost:5173](http://localhost:5173).
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspdf-utils",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Utility helpers for jsPDF's doc.html() renderer with automatic page breaking, table splitting, and RTL support",
   "type": "module",
   "main": "dist/html-to-pdf.js",