@polotno/pdf-export 0.1.34 → 0.1.36

package/README.md

@@ -94,6 +94,41 @@ await jsonToPDF(json, './output.pdf', {
 - Spot colors work best with PDF/X-1a export enabled
 - You can verify spot colors in Adobe Acrobat by checking Output Preview > Separations
 
+## DPI Handling
+
+The library automatically handles DPI conversion to ensure correct physical dimensions in the output PDF. By default, it uses the `dpi` value from your JSON file (or 72 DPI if not specified).
+
+```js
+// JSON with dpi specified
+const json = {
+  width: 1920,
+  height: 1080,
+  dpi: 300, // 300 DPI input
+  // ... rest of JSON
+};
+
+// Use JSON dpi automatically
+await jsonToPDF(json, './output.pdf');
+
+// Override DPI via attrs (takes precedence over JSON dpi)
+await jsonToPDF(json, './output.pdf', {
+  dpi: 150, // Override to 150 DPI
+});
+```
+
+**How it works:**
+
+- Input JSON coordinates are in **pixels** at the specified DPI
+- PDF uses **points** (1 point = 1/72 inch)
+- The library converts: `points = pixels × (72 / dpi)`
+- This ensures the PDF has correct physical dimensions for printing
+- All element positions, sizes, and coordinates are automatically scaled
+
+**Example:**
+
+- A 1920×1080 pixel canvas at 300 DPI = 6.4" × 3.6" in the PDF
+- The same canvas at 72 DPI = 26.67" × 15" in the PDF
+
 ## Requirements
 
 - **GhostScript** must be installed for PDF/X-1a conversion

package/lib/image.d.ts

@@ -21,6 +21,12 @@ export interface ImageElement {
     blurEnabled: boolean;
     blurRadius: number;
     filters: Record<string, ShapeFilter>;
+    shadowEnabled?: boolean;
+    shadowBlur?: number;
+    shadowOffsetX?: number;
+    shadowOffsetY?: number;
+    shadowColor?: string;
+    shadowOpacity?: number;
 }
 type ShapeFilter = {
     intensity: number;

package/lib/image.js

@@ -136,22 +136,74 @@ function applyBorder(doc, element) {
             .stroke();
     }
 }
+function saveToTempFile(buffer, key, cache) {
+    if (cache) {
+        if (!cache.imageFiles) {
+            cache.imageFiles = new Map();
+        }
+        if (!cache.tempDir) {
+            cache.tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pdfkit-images-'));
+        }
+        // Create a unique filename based on cache key hash
+        const hash = crypto.createHash('md5').update(key).digest('hex');
+        const filePath = path.join(cache.tempDir, `${hash}.png`);
+        // Write buffer to file
+        fs.writeFileSync(filePath, buffer);
+        cache.imageFiles.set(key, filePath);
+        return filePath;
+    }
+    else {
+        return buffer;
+    }
+}
+async function getShadowImage(src, element, cache) {
+    const image = await loadImage(src, cache);
+    const { shadowBlur, shadowColor, shadowOpacity } = element;
+    // Shadow blur in Konva is standard. In Canvas it is standard.
+    // We need to scale it by PIXEL_RATIO as our canvas is scaled.
+    const ratio = PIXEL_RATIO;
+    const blur = (shadowBlur || 0) * ratio;
+    // Padding.
+    const padding = blur * 4 + 20; // Sufficient padding
+    const width = image.width + padding * 2;
+    const height = image.height + padding * 2;
+    const canvas = Canvas.createCanvas(width, height);
+    const ctx = canvas.getContext('2d');
+    // Parse color
+    const parsed = parseColor(shadowColor || 'black');
+    const opacity = shadowOpacity !== undefined ? shadowOpacity : 1;
+    const r = parsed.rgb[0];
+    const g = parsed.rgb[1];
+    const b = parsed.rgb[2];
+    const a = opacity;
+    const colorString = `rgba(${r},${g},${b},${a})`;
+    ctx.shadowColor = colorString;
+    ctx.shadowBlur = blur;
+    // We want the shadow to appear at (padding, padding) relative to canvas.
+    // We draw the image at (padding - OFFSET, padding - OFFSET)
+    // And set shadowOffset to (OFFSET, OFFSET).
+    // OFFSET should be large enough to move image out of view.
+    const OFFSET = 10000;
+    ctx.shadowOffsetX = OFFSET;
+    ctx.shadowOffsetY = OFFSET;
+    // Draw image
+    ctx.drawImage(image, padding - OFFSET, padding - OFFSET, image.width, image.height);
+    return {
+        src: canvas.toDataURL('image/png'),
+        padding: padding / ratio, // return padding in original units (points)
+        width: width / ratio,
+        height: height / ratio,
+    };
+}
 export async function renderImage(doc, element, cache = null) {
     // Check if we have a cached processed version
     const cacheKey = getProcessedImageKey(element);
-    // Check if we have a cached file path for this image
-    if (cache && cache.imageFiles && cache.imageFiles.has(cacheKey)) {
-        const filePath = cache.imageFiles.get(cacheKey);
-        console.log('✓ Using cached image file:', path.basename(filePath));
-        doc.image(filePath, 0, 0, {
-            width: element.width,
-            height: element.height,
-        });
-        applyBorder(doc, element);
-        return;
-    }
     let src = null;
-    if (cache && cache.processedImages.has(cacheKey)) {
+    const hasCachedFile = cache && cache.imageFiles && cache.imageFiles.has(cacheKey);
+    if (hasCachedFile) {
+        src = cache.imageFiles.get(cacheKey);
+    }
+    else if (cache && cache.processedImages.has(cacheKey)) {
         src = cache.processedImages.get(cacheKey);
     }
     else {
@@ -165,31 +217,63 @@ export async function renderImage(doc, element, cache = null) {
             cache.processedImages.set(cacheKey, src);
         }
     }
-    if (src) {
-        const buffer = await srcToBuffer(src, cache);
-        // Save buffer to a temp file and cache the path
-        let filePath;
-        if (cache) {
-            if (!cache.imageFiles) {
-                cache.imageFiles = new Map();
-            }
-            if (!cache.tempDir) {
-                cache.tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pdfkit-images-'));
+    if (element.shadowEnabled && src) {
+        const shadowKey = cacheKey +
+            '_shadow_' +
+            JSON.stringify({
+                blur: element.shadowBlur,
+                color: element.shadowColor,
+                opacity: element.shadowOpacity,
+            });
+        let shadowPadding = 0;
+        let shadowW = 0;
+        let shadowH = 0;
+        if (cache && cache.imageFiles && cache.imageFiles.has(shadowKey)) {
+            const filePath = cache.imageFiles.get(shadowKey);
+            // Recalculate padding/dimensions as we don't cache them
+            const ratio = PIXEL_RATIO;
+            const blur = (element.shadowBlur || 0) * ratio;
+            shadowPadding = (blur * 4 + 20) / ratio;
+            shadowW = element.width + shadowPadding * 2;
+            shadowH = element.height + shadowPadding * 2;
+            console.log('✓ Using cached shadow file:', path.basename(filePath));
+            doc.image(filePath, (element.shadowOffsetX || 0) - shadowPadding, (element.shadowOffsetY || 0) - shadowPadding, {
+                width: shadowW,
+                height: shadowH,
+            });
+        }
+        else {
+            const shadowResult = await getShadowImage(src, element, cache);
+            const shadowSrc = shadowResult.src;
+            shadowPadding = shadowResult.padding;
+            shadowW = shadowResult.width;
+            shadowH = shadowResult.height;
+            if (shadowSrc) {
+                const buffer = await srcToBuffer(shadowSrc, cache);
+                const filePath = saveToTempFile(buffer, shadowKey, cache);
+                doc.image(filePath, (element.shadowOffsetX || 0) - shadowPadding, (element.shadowOffsetY || 0) - shadowPadding, {
+                    width: shadowW,
+                    height: shadowH,
+                });
             }
-            // Create a unique filename based on cache key hash
-            const hash = crypto.createHash('md5').update(cacheKey).digest('hex');
-            filePath = path.join(cache.tempDir, `${hash}.png`);
-            // Write buffer to file
-            fs.writeFileSync(filePath, buffer);
-            cache.imageFiles.set(cacheKey, filePath);
+        }
+    }
+    if (src) {
+        if (hasCachedFile) {
+            console.log('✓ Using cached image file:', path.basename(src));
+            doc.image(src, 0, 0, {
+                width: element.width,
+                height: element.height,
+            });
         }
         else {
-            filePath = buffer;
+            const buffer = await srcToBuffer(src, cache);
+            const filePath = saveToTempFile(buffer, cacheKey, cache);
+            doc.image(filePath, 0, 0, {
+                width: element.width,
+                height: element.height,
+            });
         }
-        doc.image(filePath, 0, 0, {
-            width: element.width,
-            height: element.height,
-        });
         applyBorder(doc, element);
     }
 }

package/lib/index.d.ts

@@ -10,6 +10,7 @@ export interface PolotnoJSON {
         background?: string;
         children: any[];
     }>;
+    dpi?: number;
 }
 export interface RenderAttrs {
     pdfx1a?: boolean;
@@ -22,5 +23,6 @@ export interface RenderAttrs {
     };
     spotColors?: SpotColorConfig;
     textVerticalResizeEnabled?: boolean;
+    dpi?: number;
 }
 export declare function jsonToPDF(json: PolotnoJSON, pdfFileName: string, attrs?: RenderAttrs): Promise<void>;

package/lib/index.js

@@ -3,7 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import { srcToBuffer, parseColor } from './utils.js';
 import { renderImage } from './image.js';
-import { loadFontIfNeeded, renderText } from './text.js';
+import { loadFontIfNeeded, renderText } from './text/index.js';
 import { renderFigure } from './figure.js';
 import { renderGroup } from './group.js';
 import { lineToPDF } from './line.js';
@@ -51,6 +51,13 @@ async function renderElement({ doc, element, fonts, attrs, cache, }) {
 }
 export async function jsonToPDF(json, pdfFileName, attrs = {}) {
     const fonts = {};
+    // Compute DPI and scale factor
+    // Priority: attrs.dpi (override) > json.dpi > 72 (default)
+    const inputDpi = attrs.dpi ?? json.dpi ?? 72;
+    // Validate DPI: must be finite and positive
+    const validDpi = Number.isFinite(inputDpi) && inputDpi > 0 ? inputDpi : 72;
+    // Convert pixels to PDF points: 1 point = 1/72 inch, so points per pixel = 72 / dpi
+    const ptPerPx = 72 / validDpi;
     // Create cache for images and processed results
     const cache = {
         images: new Map(), // Cache for loaded Canvas images
@@ -60,7 +67,7 @@ export async function jsonToPDF(json, pdfFileName, attrs = {}) {
         tempDir: null, // Temporary directory for image files
     };
     var doc = new PDFDocument({
-        size: [json.width, json.height],
+        size: [json.width * ptPerPx, json.height * ptPerPx],
         autoFirstPage: false,
     });
     // Enable spot color support if configured
@@ -73,6 +80,10 @@ export async function jsonToPDF(json, pdfFileName, attrs = {}) {
     }
     for (const page of json.pages) {
         doc.addPage();
+        // Apply scale transform so all pixel-based coordinates work correctly
+        // The page size is already in points, but we render in pixel coordinates
+        doc.save();
+        doc.scale(ptPerPx);
         if (page.background) {
             const isURL = page.background.indexOf('http') >= 0 ||
                 page.background.indexOf('.png') >= 0 ||
@@ -91,6 +102,7 @@ export async function jsonToPDF(json, pdfFileName, attrs = {}) {
         for (const element of page.children) {
             await renderElement({ doc, element, fonts, attrs, cache });
         }
+        doc.restore();
     }
     doc.end();
     await new Promise((r) => doc.pipe(fs.createWriteStream(pdfFileName)).on('finish', r));

package/lib/text/fonts.d.ts

@@ -0,0 +1,15 @@
+import { TextElement, TextSegment } from './types.js';
+/**
+ * Get font weight string based on bold/italic state
+ */
+export declare function getFontWeight(bold: boolean, italic: boolean, baseFontWeight?: string): string;
+/**
+ * Get font key for caching
+ */
+export declare function getFontKey(fontFamily: string, bold: boolean, italic: boolean, baseFontWeight?: string): string;
+export declare function getGoogleFontPath(fontFamily: string, fontWeight?: string, italic?: boolean): Promise<string>;
+/**
+ * Load font for a text element or segment
+ */
+export declare function loadFontForSegment(doc: any, segment: TextSegment | null, element: TextElement, fonts: Record<string, boolean>): Promise<string>;
+export declare function loadFontIfNeeded(doc: any, element: TextElement, fonts: Record<string, boolean>): Promise<string>;

package/lib/text/fonts.js

@@ -0,0 +1,67 @@
+import { srcToBuffer } from '../utils.js';
+import getUrls from 'get-urls';
+import fetch from 'node-fetch';
+/**
+ * Get font weight string based on bold/italic state
+ */
+export function getFontWeight(bold, italic, baseFontWeight) {
+    if (bold) {
+        return 'bold';
+    }
+    return baseFontWeight || 'normal';
+}
+/**
+ * Get font key for caching
+ */
+export function getFontKey(fontFamily, bold, italic, baseFontWeight) {
+    const weight = getFontWeight(bold, italic, baseFontWeight);
+    const style = italic ? 'italic' : 'normal';
+    return `${fontFamily}-${weight}-${style}`;
+}
+export async function getGoogleFontPath(fontFamily, fontWeight = 'normal', italic = false) {
+    const weight = fontWeight === 'bold' ? '700' : '400';
+    const italicParam = italic ? 'italic' : '';
+    const url = `https://fonts.googleapis.com/css?family=${fontFamily}:${italicParam}${weight}`;
+    const req = await fetch(url);
+    if (!req.ok) {
+        if (weight !== '400' || italic) {
+            // Fallback: try normal weight without italic
+            return getGoogleFontPath(fontFamily, 'normal', false);
+        }
+        throw new Error(`Failed to fetch Google font: ${fontFamily}`);
+    }
+    const text = await req.text();
+    const urls = getUrls(text);
+    return urls.values().next().value;
+}
+/**
+ * Load font for a text element or segment
+ */
+export async function loadFontForSegment(doc, segment, element, fonts) {
+    const fontFamily = element.fontFamily;
+    // Determine bold/italic from segment or element
+    const bold = segment
+        ? segment.bold || element.fontWeight == 'bold' || false
+        : element.fontWeight == 'bold';
+    const italic = segment
+        ? segment.italic || element.fontStyle?.indexOf('italic') >= 0 || false
+        : element.fontStyle?.indexOf('italic') >= 0 || false;
+    // Check if universal font is already defined
+    if (fonts[fontFamily]) {
+        doc.font(fontFamily);
+        return fontFamily;
+    }
+    const fontKey = getFontKey(fontFamily, bold, italic, element.fontWeight);
+    if (!fonts[fontKey]) {
+        const weight = getFontWeight(bold, italic, element.fontWeight);
+        const src = await getGoogleFontPath(fontFamily, weight, italic);
+        doc.registerFont(fontKey, await srcToBuffer(src));
+        fonts[fontKey] = true;
+    }
+    doc.font(fontKey);
+    return fontKey;
+}
+// Alias for backward compatibility
+export async function loadFontIfNeeded(doc, element, fonts) {
+    return loadFontForSegment(doc, null, element, fonts);
+}

package/lib/text/index.d.ts

@@ -0,0 +1,8 @@
+import { TextElement, RenderAttrs } from './types.js';
+export * from './types.js';
+export { loadFontIfNeeded } from './fonts.js';
+export { normalizeRichText, parseHTMLToSegments } from './parser.js';
+/**
+ * Main text rendering function
+ */
+export declare function renderText(doc: PDFKit.PDFDocument, element: TextElement, fonts: Record<string, boolean>, attrs?: RenderAttrs): Promise<void>;

package/lib/text/index.js

@@ -0,0 +1,42 @@
+import { normalizeRichText } from './parser.js';
+import { calculateTextMetrics, calculateVerticalAlignment, fitTextToHeight, } from './layout.js';
+import { renderTextBackground, renderPDFX1aStroke, renderStandardStroke, renderTextFill, } from './render.js';
+export * from './types.js';
+export { loadFontIfNeeded } from './fonts.js';
+export { normalizeRichText, parseHTMLToSegments } from './parser.js';
+/**
+ * Main text rendering function
+ */
+export async function renderText(doc, element, fonts, attrs = {}) {
+    let elementToRender = element;
+    if (typeof element.text === 'string') {
+        const normalizedText = normalizeRichText(element.text);
+        if (normalizedText !== element.text) {
+            elementToRender = { ...element, text: normalizedText };
+        }
+    }
+    doc.fontSize(elementToRender.fontSize);
+    const hasStroke = elementToRender.strokeWidth > 0;
+    const isPDFX1a = attrs.pdfx1a;
+    // Calculate text metrics and line positioning
+    const metrics = calculateTextMetrics(doc, elementToRender);
+    const verticalAlignmentOffset = calculateVerticalAlignment(doc, elementToRender, metrics.textOptions);
+    // Fit text to element height if needed
+    fitTextToHeight(doc, elementToRender, metrics.textOptions);
+    // Calculate final vertical offset
+    const finalYOffset = verticalAlignmentOffset + metrics.baselineOffset;
+    // Render background if enabled
+    renderTextBackground(doc, elementToRender, verticalAlignmentOffset, metrics.textOptions);
+    // Render text based on stroke and PDF/X-1a requirements
+    if (hasStroke && isPDFX1a) {
+        // PDF/X-1a mode: simulate stroke with offset fills
+        await renderPDFX1aStroke(doc, elementToRender, metrics.textLines, finalYOffset, metrics.lineHeightPx, metrics.textOptions, fonts);
+    }
+    else {
+        // Standard rendering: stroke first, then fill
+        if (hasStroke) {
+            await renderStandardStroke(doc, elementToRender, metrics.textLines, finalYOffset, metrics.lineHeightPx, metrics.textOptions, fonts);
+        }
+        await renderTextFill(doc, elementToRender, metrics.textLines, finalYOffset, metrics.lineHeightPx, metrics.textOptions, fonts);
+    }
+}

package/lib/text/layout.d.ts

@@ -0,0 +1,22 @@
+import { TextElement, TextLine, TextMetrics, RenderSegment, TabExpansionSegment } from './types.js';
+/**
+ * Expand tabs in text with word spacing adjustment for accurate visual alignment.
+ */
+export declare function expandTabsWithWordSpacing(text: string, doc: PDFKit.PDFDocument, textOptions: PDFKit.Mixins.TextOptions, tabSizeInSpaces?: number, currentWidth?: number): {
+    segments: TabExpansionSegment[];
+    finalWidth: number;
+};
+export declare function buildRenderSegmentsForLine(doc: PDFKit.PDFDocument, element: TextElement, lineText: string, textOptions: PDFKit.Mixins.TextOptions, fonts: Record<string, boolean>): Promise<RenderSegment[]>;
+export declare function splitTextIntoLines(doc: PDFKit.PDFDocument, element: TextElement, props: PDFKit.Mixins.TextOptions): TextLine[];
+export declare function calculateTextMetrics(doc: PDFKit.PDFDocument, element: TextElement): TextMetrics;
+export declare function calculateVerticalAlignment(doc: PDFKit.PDFDocument, element: TextElement, textOptions: PDFKit.Mixins.TextOptions): number;
+export declare function fitTextToHeight(doc: PDFKit.PDFDocument, element: TextElement, textOptions: PDFKit.Mixins.TextOptions): void;
+/**
+ * Calculate X offset for list markers (not used for text content positioning)
+ */
+export declare function calculateLineXOffset(element: TextElement, line: TextLine): number;
+export declare function calculateTextContentXOffset(element: TextElement, line: TextLine): number;
+/**
+ * Calculate effective width for text rendering, considering justify and underline constraints
+ */
+export declare function calculateEffectiveWidth(element: TextElement, line: TextLine, widthOption: number | undefined, hasUnderline: boolean): number | undefined;