smart-pdf-js 1.0.0

package/README.md

@@ -0,0 +1,208 @@
+# Smart PDF
+
+[![npm version](https://img.shields.io/npm/v/smart-pdf.svg)](https://www.npmjs.com/package/smart-pdf)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Downloads](https://img.shields.io/npm/dt/smart-pdf.svg)](https://www.npmjs.com/package/smart-pdf)
+
+**The ultimate DOM-to-PDF solution for modern web applications.**
+
+`smart-pdf` is a powerful, lightweight, and developer-friendly wrapper around `html2canvas` and `jspdf`. It simplifies the complex process of generating multi-page PDFs from HTML, making it easy to turn your React, Next.js, or vanilla JavaScript web pages into professional-quality PDF documents.
+
+Unlike standard libraries, `smart-pdf` comes with built-in support for modern CSS features like **OKLCH colors**, ensuring your PDF looks exactly as intended.
+
+---
+
+## Key Features
+
+- **Multi-page Generation**: Effortlessly split your content across multiple pages using simple CSS selectors.
+- ** OKLCH Color Support**: First-class support for modern CSS color spaces, automatically converting OKLCH to RGB for perfect rendering.
+- ** React & Next.js Ready**: Designed to work seamlessly with modern component-based frameworks.
+- ** Highly Configurable**: Full control over margins, orientation, formats (A4, Letter, etc.), and image quality.
+- ** Lightweight**: Zero configuration needed for most use cases—just install and generate.
+
+---
+
+## 📦 Installation
+
+Install the package via npm, yarn, or pnpm:
+
+```bash
+# npm
+npm install smart-pdf
+
+```
+
+---
+
+## 💡 Usage
+
+### 1. Vanilla JavaScript / Basic Usage
+
+The simplest way to use `smart-pdf` is to define the sections you want to capture and call `generatePDF`.
+
+```javascript
+import { generatePDF } from "smart-pdf";
+
+const config = {
+  filename: "monthly-report.pdf",
+  pages: [
+    {
+      // First page content from element with ID 'page1'
+      from: "#page1-start",
+      to: "#page1-end",
+    },
+    {
+      // Second page content
+      from: ".section-2-start",
+      to: ".section-2-end",
+    },
+  ],
+};
+
+document.getElementById("download-btn").addEventListener("click", () => {
+  generatePDF(config).then(() => {
+    console.log("PDF successfully downloaded!");
+  });
+});
+```
+
+---
+
+### 2. Using with React
+
+In React, you can use `useRef` to target elements, but using unique IDs or classes is often simpler for dynamic content.
+
+```jsx
+import React from "react";
+import { generatePDF } from "smart-pdf";
+
+const PDFReport = () => {
+  const handleDownload = async () => {
+    const config = {
+      filename: "react-report.pdf",
+      pages: [{ from: "#report-header", to: "#report-footer" }],
+      jsPDFOptions: { orientation: "landscape" },
+    };
+
+    await generatePDF(config);
+  };
+
+  return (
+    <div>
+      <div id="report-header">
+        <h1>Monthly Analytics</h1>
+      </div>
+
+      {/* Your complex content charts, tables, etc. */}
+      <div className="content">
+        <p>This content will be included in the PDF.</p>
+      </div>
+
+      <div id="report-footer">
+        <p>End of Report</p>
+      </div>
+
+      <button onClick={handleDownload} className="btn-primary">
+        Download PDF
+      </button>
+    </div>
+  );
+};
+
+export default PDFReport;
+```
+
+---
+
+### 3. Using with Next.js (App Router & Pages Router)
+
+Since `smart-pdf` relies on browser APIs (`window`, `document`), it must be dynamically imported with `ssr: false` or used inside `useEffect` / event handlers to avoid Server-Side Rendering (SSR) errors like `ReferenceError: document is not defined`.
+
+#### Method A: Inside a Client Component (Recommended for App Router)
+
+```jsx
+"use client"; // Important for App Router
+
+import React from "react";
+
+// You can import directly if function is called on an event (click)
+// as the import will be resolved on the client.
+
+import { generatePDF } from "smart-pdf";
+
+export default function InvoicePage() {
+  const downloadInvoice = async () => {
+    // Alternatively, dynamic import inside the function for cleaner bundle splitting
+    // const { generatePDF } = await import('smart-pdf');
+
+    await generatePDF({
+      filename: "invoice-123.pdf",
+      pages: [{ from: ".invoice-start", to: ".invoice-end" }],
+    });
+  };
+
+  return (
+    <main>
+      <div className="invoice-start">Invoice Header</div>
+      {/* Invoice Details */}
+      <div className="invoice-end">Thank you for your business</div>
+
+      <button onClick={downloadInvoice}>Download Invoice</button>
+    </main>
+  );
+}
+```
+
+#### Method B: Dynamic Import Component
+
+If you need to render the component conditionally or simply want to ensure isolation:
+
+```javascript
+import dynamic from "next/dynamic";
+
+const PDFButton = dynamic(() => import("../components/PDFButton"), {
+  ssr: false,
+});
+
+export default function Page() {
+  return <PDFButton />;
+}
+```
+
+---
+
+## ⚙️ Configuration (API Reference)
+
+The `generatePDF(config)` function accepts a configuration object.
+
+### `PDFConfig` Object
+
+| Property                 | Type     | Default                        | Description                                                                                         |
+| :----------------------- | :------- | :----------------------------- | :-------------------------------------------------------------------------------------------------- |
+| **`pages`**              | `Array`  | **Required**                   | An array of objects defining the content for each page.                                             |
+| **`filename`**           | `string` | `"document.pdf"`               | The name of the output file.                                                                        |
+| **`jsPDFOptions`**       | `object` | `{ unit: 'mm', format: 'a4' }` | Options passed to `new jsPDF()`. See [jsPDF docs](http://raw.githack.com/MrRio/jsPDF/master/docs/). |
+| **`html2canvasOptions`** | `object` | `{ scale: 2, useCORS: true }`  | Options passed to `html2canvas()`. `scale: 2` improves quality for retina displays.                 |
+
+### `pages` Array Item
+
+| Property   | Type     | Description                                                                              |
+| :--------- | :------- | :--------------------------------------------------------------------------------------- |
+| **`from`** | `string` | **CSS Selector** (e.g., `#start-id`, `.class-name`) marking the **beginning** of a page. |
+| **`to`**   | `string` | **CSS Selector** marking the **end** of a page.                                          |
+
+> **Note:** The library captures everything _between_ the `from` and `to` elements (inclusive) in the DOM order.
+
+---
+
+## Best Practices & Tips
+
+1.  **Image Loading (CORS)**: If your PDF contains images from external URLs, you might face CORS issues.
+    - Ensure your images are served with `Access-Control-Allow-Origin: *`.
+    - Set `html2canvasOptions: { useCORS: true }` in the config (enabled by default).
+2.  **Hiding Elements**: To hide buttons or controls in the generated PDF, use a CSS class (e.g., `.no-print`) and apply `opacity: 0` or unique styling during captured rendering, or temporary DOM manipulation.
+3.  **Fonts**: For custom fonts to render correctly, ensure they are fully loaded before generating the PDF. `document.fonts.ready` can be useful.
+
+## 📄 License
+
+MIT © [Rashedul Haque Rasel](https://github.com/RashedulHaqueRasel1)

package/index.d.ts

@@ -0,0 +1,6 @@
+export interface PDFConfig {
+  pages: { from: string; to: string }[];
+  filename?: string;
+}
+
+export function generatePDF(config: PDFConfig): Promise<void>;

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "smart-pdf-js",
+  "version": "1.0.0",
+  "description": "A powerful and easy-to-use library to generate PDFs from DOM elements, with support for OKLCH colors and multi-page documents.",
+  "main": "src/index.js",
+  "keywords": [
+    "pdf",
+    "html2canvas",
+    "jspdf",
+    "dom-to-pdf",
+    "oklch",
+    "pdf-generation"
+  ],
+  "author": "Rashedul Haque Rasel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RashedulHaqueRasel1/smart-pdf.git"
+  },
+  "bugs": {
+    "url": "https://github.com/RashedulHaqueRasel1/smart-pdf/issues"
+  },
+  "homepage": "https://github.com/RashedulHaqueRasel1/smart-pdf#readme",
+  "dependencies": {
+    "html2canvas": "^1.4.1",
+    "jspdf": "^2.5.1"
+  }
+}

package/src/generatePDF.js

@@ -0,0 +1,202 @@
+import html2canvas from "html2canvas";
+import jsPDF from "jspdf";
+
+/**
+ * Validates the configuration object.
+ * @param {Object} config - The configuration object.
+ * @throws {Error} If the configuration is invalid.
+ */
+function validateConfig(config) {
+  if (!config || typeof config !== "object") {
+    throw new Error("Configuration object is required.");
+  }
+  if (!config.pages || !Array.isArray(config.pages) || config.pages.length === 0) {
+    throw new Error("Configuration must include a non-empty 'pages' array.");
+  }
+}
+
+/**
+ * Extracts content from the DOM based on selectors.
+ * @param {string} from - Selector for the start element.
+ * @param {string} to - Selector for the end element.
+ * @returns {DocumentFragment} The extracted content.
+ */
+function getRangeContent(from, to) {
+  const startEl = document.querySelector(from);
+  const endEl = document.querySelector(to);
+
+  if (!startEl || !endEl) {
+    throw new Error(`Invalid selectors provided: from '${from}', to '${to}'`);
+  }
+
+  const range = document.createRange();
+  range.setStartBefore(startEl);
+  range.setEndAfter(endEl);
+
+  return range.cloneContents();
+}
+
+/**
+ * Creates a hidden container to render the content for PDF generation.
+ * @param {string} width - Width of the container.
+ * @returns {HTMLElement} The created container.
+ */
+function createHiddenContainer(width = "794px") {
+  const container = document.createElement("div");
+  Object.assign(container.style, {
+    position: "fixed",
+    left: "-9999px",
+    top: "0",
+    width: width,
+    background: "white",
+    padding: "20px",
+    boxSizing: "border-box", // Ensure padding doesn't affect width
+  });
+
+  document.body.appendChild(container);
+  return container;
+}
+
+/**
+ * Converts OKLCH colors to RGBA for canvas compatibility.
+ * @param {string} color - The color string.
+ * @param {CanvasRenderingContext2D} ctx - A canvas context for color processing.
+ * @returns {string} The collected RGBA color.
+ */
+function forceRgb(color, ctx) {
+  if (!color || typeof color !== "string" || !color.includes("oklch")) {
+    return color;
+  }
+  return color.replace(/oklch\([^)]+\)/g, (match) => {
+    ctx.clearRect(0, 0, 1, 1);
+    ctx.fillStyle = match;
+    ctx.fillRect(0, 0, 1, 1);
+    const data = ctx.getImageData(0, 0, 1, 1).data;
+    // data[3] is alpha in 0-255 range, rgba needs 0-1
+    return `rgba(${data[0]}, ${data[1]}, ${data[2]}, ${data[3] / 255})`;
+  });
+}
+
+/**
+ * Processes an element and its children to convert OKLCH colors to RGB.
+ * @param {HTMLElement} element - The root element to process.
+ */
+function processOklchColors(element) {
+  const canvas = document.createElement("canvas");
+  canvas.width = 1;
+  canvas.height = 1;
+  const ctx = canvas.getContext("2d");
+
+  const elements = [element, ...element.getElementsByTagName("*")];
+  
+  for (const el of elements) {
+    const style = window.getComputedStyle(el);
+
+    // Iterating over all properties
+    for (let i = 0; i < style.length; i++) {
+        const prop = style[i];
+        const val = style.getPropertyValue(prop);
+        if (val && val.includes("oklch")) {
+            el.style.setProperty(
+                prop,
+                forceRgb(val, ctx),
+                style.getPropertyPriority(prop)
+            );
+        }
+    }
+      
+    // Handle specific shorthand/computed properties aggressively
+    const extraProps = ["backgroundImage", "boxShadow", "fill", "stroke", "color", "borderColor", "backgroundColor"];
+    for (const prop of extraProps) {
+       const val = style[prop];
+       // Computed style access for camelCase properties
+       if (val && typeof val === 'string' && val.includes("oklch")) {
+          // We convert camelCase to kebab-case for setProperty if needed, but direct style assignment works too
+          // Using strict style assignment for these specific overrides
+           el.style[prop] = forceRgb(val, ctx);
+       }
+    }
+  }
+}
+
+
+/**
+ * Generates a PDF from specified DOM elements.
+ * @param {Object} config - Configuration options.
+ * @param {Array<{from: string, to: string}>} config.pages - Array of page definitions with selectors.
+ * @param {string} [config.filename="document.pdf"] - Output filename.
+ * @param {Object} [config.jsPDFOptions] - Options for jsPDF constructor.
+ * @param {Object} [config.html2canvasOptions] - Options for html2canvas.
+ * @returns {Promise<void>}
+ */
+export async function generatePDF(config) {
+  validateConfig(config);
+
+  const { 
+    pages, 
+    filename = "document.pdf", 
+    jsPDFOptions = { orientation: "p", unit: "mm", format: "a4" },
+    html2canvasOptions = {}
+  } = config;
+
+  const pdf = new jsPDF(jsPDFOptions);
+  let isFirstPage = true;
+
+  // Defaults for A4 size in mm roughly map to pixels at 96 DPI
+  const pageWidthPx = 794; 
+
+  for (const page of pages) {
+    const { from, to } = page;
+
+    let container;
+    try {
+      const content = getRangeContent(from, to);
+      container = createHiddenContainer(`${pageWidthPx}px`);
+      container.appendChild(content);
+
+      // Mutate the DOM in the hidden container to fix OKLCH colors
+      processOklchColors(container);
+
+      const canvas = await html2canvas(container, {
+        scale: 2, // Higher scale for better resolution
+        useCORS: true,
+        windowWidth: pageWidthPx,
+        onclone: (clonedDoc) => {
+            // Re-run color processing on the cloned document used by html2canvas
+            const clonedContainer = clonedDoc.body.lastChild;
+            if (clonedContainer) {
+                 processOklchColors(clonedContainer);
+            }
+        },
+        ...html2canvasOptions,
+      });
+
+      const imgData = canvas.toDataURL("image/png");
+      const pdfWidth = pdf.internal.pageSize.getWidth();
+      const pdfHeight = (canvas.height * pdfWidth) / canvas.width;
+
+      if (!isFirstPage) {
+        pdf.addPage();
+      }
+
+      pdf.addImage(imgData, "PNG", 0, 0, pdfWidth, pdfHeight);
+      isFirstPage = false;
+    } catch (error) {
+       console.error(`Error processing page with selectors ${from} -> ${to}:`, error);
+       // Continue to next page or re-throw based on preference?
+       // For now, we log and continue to try to render partial document, 
+       // but strictly speaking we might want to reject. 
+       // Let's rethrow to inform the user the PDF generation failed.
+       if (container && container.parentNode) {
+            document.body.removeChild(container);
+       }
+       throw error;
+    }
+
+    if (container && container.parentNode) {
+      document.body.removeChild(container);
+    }
+  }
+
+  pdf.save(filename);
+}

package/src/index.js

@@ -0,0 +1 @@
+export { generatePDF } from "./generatePDF";