fabricjs-document-engine 1.0.2 → 1.2.0

package/dist/pdf/export-pdf.cjs

@@ -0,0 +1,381 @@
+const require_errors = require("../engine/errors.cjs");
+const require_object_ids = require("../fabric/object-ids.cjs");
+const require_walk_objects = require("../fabric/walk-objects.cjs");
+const require_overrides = require("../export/svg/overrides.cjs");
+const require_text_on_path = require("../export/svg/text-on-path.cjs");
+const require_raster_object = require("../export/svg/raster-object.cjs");
+const require_text_decorations = require("../export/svg/text-decorations.cjs");
+const require_render_export = require("../export/render-export.cjs");
+const require_embed_assets = require("../export/svg/embed-assets.cjs");
+const require_batch_render = require("../export/batch-render.cjs");
+const require_fonts = require("./fonts.cjs");
+const require_page_layout = require("./page-layout.cjs");
+//#region src/pdf/export-pdf.ts
+const RASTER_REASONS = {
+	shadow: "it has a shadow, which PDF vectors cannot draw",
+	blend: "it uses a blend mode, which PDF vectors cannot draw",
+	gradientStroke: "its outline is a gradient or pattern",
+	uniformStroke: "it keeps its outline width while scaled (strokeUniform)",
+	font: "its font has no TrueType file in fonts",
+	characters: "it uses characters the built-in PDF fonts do not have; add a TrueType font that has them",
+	mask: "it uses an inverted or nested clip path, which PDF vectors cannot draw"
+};
+function stop(signal) {
+	if (signal?.aborted) throw new require_errors.DocumentEngineError("EXPORT_ABORTED", "The PDF export was cancelled");
+}
+async function loadPeers(needsSvg) {
+	let jsPDF;
+	try {
+		jsPDF = (await import("jspdf")).jsPDF;
+	} catch (error) {
+		throw new require_errors.DocumentEngineError("PDF_UNAVAILABLE", "PDF export needs the jspdf package. Install it with: npm install jspdf svg2pdf.js", { cause: error });
+	}
+	if (needsSvg) try {
+		await import("svg2pdf.js");
+	} catch (error) {
+		throw new require_errors.DocumentEngineError("PDF_UNAVAILABLE", "Vector and hybrid PDF export need the svg2pdf.js package. Install it with: npm install svg2pdf.js, or use mode: \"raster\".", { cause: error });
+	}
+	return jsPDF;
+}
+function isEngine(source) {
+	return typeof source.toDocument === "function" && "canvas" in source;
+}
+function isCanvas(source) {
+	const candidate = source;
+	return typeof candidate.getObjects === "function" && typeof candidate.toCanvasElement === "function";
+}
+function idsOf(object) {
+	const ids = [];
+	require_walk_objects.walkObjects([object], (child) => {
+		const id = require_object_ids.readObjectId(child);
+		if (id !== void 0) ids.push(id);
+	});
+	return ids.slice(0, 1);
+}
+function familiesOf(object) {
+	const text = object;
+	const families = /* @__PURE__ */ new Set();
+	if (typeof text.fontFamily === "string") families.add(text.fontFamily);
+	for (const line of Object.values(text.styles ?? {})) for (const style of Object.values(line ?? {})) if (typeof style?.fontFamily === "string") families.add(style.fontFamily);
+	return [...families];
+}
+function resolvesTo(family, registered) {
+	const names = family.split(",").map((name) => name.trim().replace(/^['"]|['"]$/g, ""));
+	if (names.some((name) => registered.families.has(name.toLowerCase()))) return {
+		registered: true,
+		standard: false
+	};
+	return {
+		registered: false,
+		standard: names.some((name) => require_fonts.standardFamily(name) !== void 0)
+	};
+}
+/** Why an object cannot be drawn as PDF vectors, or undefined when it can. */
+function rasterReason(object, registered, missingFonts) {
+	let reason;
+	require_walk_objects.walkObjects([object], (child) => {
+		if (reason) return;
+		if (child.shadow) reason = "shadow";
+		else if (child.clipPath?.inverted || child.clipPath?.clipPath) reason = "mask";
+		else if (child.globalCompositeOperation && child.globalCompositeOperation !== "source-over") reason = "blend";
+		else if (typeof child.stroke === "object" && child.stroke !== null && child.strokeWidth > 0) reason = "gradientStroke";
+		else if (child.strokeUniform && child.stroke && child.strokeWidth > 0) {
+			const { x: scaleX, y: scaleY } = child.getObjectScaling();
+			if (Math.abs(scaleX - 1) > 1e-6 || Math.abs(scaleY - 1) > 1e-6) reason = "uniformStroke";
+		}
+		const text = child.text;
+		if (!reason && typeof text === "string") {
+			const families = familiesOf(child).map((family) => resolvesTo(family, registered));
+			const allRegistered = families.every((family) => family.registered);
+			if (!allRegistered && /[^\u0000-ÿ]/.test(text)) reason = "characters";
+			else if (!allRegistered && missingFonts === "rasterize" && families.some((family) => !family.registered && !family.standard)) reason = "font";
+		}
+	});
+	return reason;
+}
+function quoteFamily(name) {
+	return /^[a-z-]+$/i.test(name) ? name : `"${name.replace(/"/g, "")}"`;
+}
+function resolveFamily(list, registered) {
+	const names = list.split(",").map((name) => name.trim().replace(/^['"]|['"]$/g, ""));
+	for (const name of names) {
+		const own = registered.families.get(name.toLowerCase());
+		if (own) return quoteFamily(own);
+	}
+	for (const name of names) {
+		const standard = require_fonts.standardFamily(name);
+		if (standard) return standard;
+	}
+	return "helvetica";
+}
+function weightOf(value) {
+	const number = Number(value);
+	return value === "bold" || value === "bolder" || Number.isFinite(number) && number >= 600 ? "bold" : "normal";
+}
+/**
+* Points every font at a font jsPDF has, and rounds weights to normal or
+* bold. svg2pdf matches family names exactly and otherwise falls back to
+* Times, and it looks for weights such as 500 as styles no font has.
+*/
+function normalizeFonts(root, registered) {
+	for (const element of [root, ...Array.from(root.getElementsByTagName("*"))]) {
+		const family = element.getAttribute("font-family");
+		if (family) element.setAttribute("font-family", resolveFamily(family, registered));
+		const weight = element.getAttribute("font-weight");
+		if (weight) element.setAttribute("font-weight", weightOf(weight));
+		const style = element.getAttribute("style");
+		if (style && /font-(family|weight)/.test(style)) element.setAttribute("style", style.replace(/font-family:\s*([^;]+)/g, (_, value) => `font-family: ${resolveFamily(value, registered)}`).replace(/font-weight:\s*([^;]+)/g, (_, value) => `font-weight: ${weightOf(value.trim())}`));
+	}
+}
+/** Warns once for each family and style the canvas uses that has no file of its own. */
+function warnSubstitutedStyles(canvas, registered, page, warnings, warned) {
+	if (registered.substituted.length === 0) return;
+	const missing = new Set(registered.substituted.map(({ family, style }) => `${family.toLowerCase()}|${style}`));
+	require_walk_objects.walkObjects(canvas.getObjects(), (object) => {
+		const text = object;
+		if (typeof text.text !== "string") return;
+		const uses = [{
+			family: text.fontFamily,
+			weight: text.fontWeight,
+			style: text.fontStyle
+		}];
+		for (const line of Object.values(text.styles ?? {})) for (const style of Object.values(line ?? {})) uses.push({
+			family: style?.fontFamily ?? text.fontFamily,
+			weight: style?.fontWeight ?? text.fontWeight,
+			style: style?.fontStyle ?? text.fontStyle
+		});
+		for (const use of uses) {
+			const family = registered.families.get(String(use.family ?? "").toLowerCase());
+			if (!family) continue;
+			const style = require_fonts.jsPdfStyle(use.weight, use.style);
+			const key = `${family.toLowerCase()}|${style}`;
+			if (!missing.has(key) || warned.has(key)) continue;
+			warned.add(key);
+			warnings.push({
+				code: "PDF_FONT_SUBSTITUTED",
+				message: `No ${style} file was given for "${family}", so its ${style} text uses another file of the same family`,
+				page,
+				objectIds: idsOf(object),
+				family
+			});
+		}
+	});
+}
+function clipTo(context, draw) {
+	const clip = context.layout.clip;
+	if (!clip) return draw();
+	const { document } = context;
+	document.saveGraphicsState();
+	document.rect(clip.x, clip.y, clip.width, clip.height, null);
+	document.clip();
+	document.discardPath();
+	const finish = () => {
+		document.restoreGraphicsState();
+	};
+	const drawn = draw();
+	if (drawn instanceof Promise) return drawn.finally(finish);
+	finish();
+}
+async function drawRasterPage(canvas, context) {
+	const { layout, options } = context;
+	const multiplier = require_raster_object.safeMultiplier(layout.scale * (options.dpi ?? 300) / 72, canvas.getWidth(), canvas.getHeight(), options.limits);
+	const element = require_render_export.withExportView(canvas, options.background ?? "keep", "png", () => canvas.toCanvasElement(multiplier));
+	try {
+		await clipTo(context, () => {
+			context.document.addImage(element, "PNG", layout.x, layout.y, layout.width, layout.height, void 0, "FAST");
+		});
+	} finally {
+		element.width = 0;
+		element.height = 0;
+	}
+}
+async function drawVectorPage(canvas, context) {
+	const { layout, options, page, warnings, registered } = context;
+	const mode = options.mode ?? "hybrid";
+	const missingFonts = options.missingFonts ?? (mode === "hybrid" ? "rasterize" : "substitute");
+	const multiplier = layout.scale * (options.dpi ?? 300) / 72;
+	const width = canvas.getWidth();
+	const height = canvas.getHeight();
+	const svg = require_render_export.withExportView(canvas, options.background ?? "keep", "svg", () => {
+		const rasters = /* @__PURE__ */ new Map();
+		for (const object of canvas.getObjects()) {
+			const reason = rasterReason(object, registered, missingFonts);
+			if (!reason) continue;
+			if (mode === "hybrid") {
+				rasters.set(object, require_raster_object.rasterMarkup(canvas, object, multiplier, options.limits));
+				warnings.push({
+					code: "PDF_RASTERIZED",
+					message: `An object was drawn as a picture at ${options.dpi ?? 300} dpi because ${RASTER_REASONS[reason]}`,
+					page,
+					objectIds: idsOf(object)
+				});
+			} else warnings.push({
+				code: reason === "font" || reason === "characters" ? "PDF_FONT_SUBSTITUTED" : "PDF_UNSUPPORTED",
+				message: `An object may look different in the PDF because ${RASTER_REASONS[reason]}`,
+				page,
+				objectIds: idsOf(object)
+			});
+		}
+		const writerFor = (object) => {
+			const raster = rasters.get(object);
+			if (raster !== void 0) return () => raster;
+			if (require_text_on_path.isTextOnPath(object)) return (reviver) => require_text_on_path.textOnPathToSVG(object, reviver);
+			if (require_text_decorations.hasStraightDecorations(object)) return (reviver) => require_text_decorations.decoratedTextToSVG(object, reviver);
+		};
+		return require_overrides.withSvgOverrides(canvas, writerFor, () => canvas.toSVG({
+			viewBox: {
+				x: 0,
+				y: 0,
+				width,
+				height
+			},
+			width: String(width),
+			height: String(height)
+		})).result;
+	});
+	const embedded = await require_embed_assets.embedSvgAssets(require_render_export.repairFabricSvg(svg), canvas, {
+		textOnPath: "vector",
+		textDecorations: "shapes",
+		embedImages: true,
+		maxEmbeddedImageBytes: Number.MAX_SAFE_INTEGER,
+		embedFonts: {}
+	}, options.signal);
+	stop(options.signal);
+	for (const warning of embedded.warnings) if (warning.code === "IMAGE_NOT_EMBEDDED") warnings.push({
+		code: "IMAGE_NOT_EMBEDDED",
+		message: warning.message,
+		page,
+		objectIds: warning.objectIds,
+		url: warning.url
+	});
+	const root = new DOMParser().parseFromString(embedded.svg, "image/svg+xml").documentElement;
+	normalizeFonts(root, registered);
+	await clipTo(context, async () => {
+		await context.document.svg(root, {
+			x: layout.x,
+			y: layout.y,
+			width: layout.width,
+			height: layout.height
+		});
+	});
+}
+/**
+* Exports one or more pages as a PDF. Each source becomes one page: an
+* engine's canvas, a Fabric canvas, or a saved document, which is drawn on
+* an off-screen canvas that is freed after its page.
+*/
+async function exportPdf(sources, options = {}) {
+	const list = Array.isArray(sources) ? [...sources] : [sources];
+	if (list.length === 0) throw new require_errors.DocumentEngineError("INVALID_EXPORT_OPTIONS", "exportPdf needs at least one page");
+	const dpi = options.dpi ?? 300;
+	if (!(Number.isFinite(dpi) && dpi > 0 && dpi <= 1200)) throw new require_errors.DocumentEngineError("INVALID_EXPORT_OPTIONS", "dpi must be between 1 and 1200");
+	const mode = options.mode ?? "hybrid";
+	if (![
+		"vector",
+		"raster",
+		"hybrid"
+	].includes(mode)) throw new require_errors.DocumentEngineError("INVALID_EXPORT_OPTIONS", "mode must be \"vector\", \"raster\" or \"hybrid\"");
+	if (typeof document === "undefined") throw new require_errors.DocumentEngineError("PDF_UNAVAILABLE", "PDF export needs a browser DOM");
+	stop(options.signal);
+	const jsPDF = await loadPeers(mode !== "raster");
+	const fonts = await require_fonts.loadFonts(options.fonts ?? [], options.signal);
+	stop(options.signal);
+	let pdf;
+	let registered = {
+		families: /* @__PURE__ */ new Map(),
+		substituted: []
+	};
+	const warnings = [];
+	const warnedStyles = /* @__PURE__ */ new Set();
+	let renderer;
+	try {
+		for (let index = 0; index < list.length; index += 1) {
+			stop(options.signal);
+			const source = list[index];
+			let canvas;
+			if (isEngine(source)) canvas = source.canvas;
+			else if (isCanvas(source)) canvas = source;
+			else {
+				renderer ?? (renderer = await createRenderer(options));
+				await renderer.engine.loadDocument(source, {
+					signal: options.signal,
+					discardUnsavedChanges: true
+				});
+				canvas = renderer.canvas;
+			}
+			const layout = require_page_layout.layoutPage({
+				width: canvas.getWidth(),
+				height: canvas.getHeight()
+			}, options);
+			const format = [layout.pageWidth, layout.pageHeight];
+			if (!pdf) {
+				pdf = new jsPDF({
+					unit: "pt",
+					format,
+					orientation: layout.orientation,
+					compress: true,
+					putOnlyUsedFonts: true
+				});
+				registered = require_fonts.registerFonts(pdf, fonts);
+			} else pdf.addPage(format, layout.orientation);
+			warnSubstitutedStyles(canvas, registered, index + 1, warnings, warnedStyles);
+			const context = {
+				document: pdf,
+				layout,
+				options,
+				registered,
+				page: index + 1,
+				warnings
+			};
+			if (mode === "raster") await drawRasterPage(canvas, context);
+			else await drawVectorPage(canvas, context);
+			if (renderer && canvas === renderer.canvas) require_batch_render.disposeObjects(renderer.canvas);
+		}
+		stop(options.signal);
+		const { metadata } = options;
+		pdf.setProperties({
+			creator: metadata?.creator ?? "fabricjs-document-engine",
+			...metadata
+		});
+		return {
+			blob: pdf.output("blob"),
+			pageCount: list.length,
+			warnings
+		};
+	} catch (error) {
+		if (require_errors.isDocumentEngineError(error)) throw error;
+		if (options.signal?.aborted) throw new require_errors.DocumentEngineError("EXPORT_ABORTED", "The PDF export was cancelled", { cause: error });
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new require_errors.DocumentEngineError("PDF_FAILED", `The PDF could not be made: ${reason}`, { cause: error });
+	} finally {
+		await renderer?.release();
+	}
+}
+async function createRenderer(options) {
+	const [{ StaticCanvas }, { createDocumentEngine }] = await Promise.all([import("fabric"), Promise.resolve().then(() => require("../engine/create-document-engine.cjs"))]);
+	const element = document.createElement("canvas");
+	const canvas = new StaticCanvas(element, {
+		renderOnAddRemove: false,
+		enableRetinaScaling: false
+	});
+	const engine = createDocumentEngine({
+		canvas,
+		customObjects: options.customObjects,
+		assets: options.assets,
+		limits: options.limits,
+		history: { limit: 1 }
+	});
+	return {
+		canvas,
+		engine,
+		release: async () => {
+			require_batch_render.disposeObjects(canvas);
+			engine.destroy();
+			await canvas.dispose();
+			element.width = 0;
+			element.height = 0;
+		}
+	};
+}
+//#endregion
+exports.exportPdf = exportPdf;

package/dist/pdf/export-pdf.d.cts

@@ -0,0 +1,73 @@
+import { FabricDocument } from "../document/document-format.cjs";
+import { AssetOptions } from "../assets/asset-pipeline.cjs";
+import { ExportBackground } from "../export/export-options.cjs";
+import { ContentLimits } from "../security/content-limits.cjs";
+import { CustomObjectDefinition } from "../fabric/object-registry.cjs";
+import { DocumentEngine } from "../engine/create-document-engine.cjs";
+import { PdfFont } from "./fonts.cjs";
+import { PageLayoutOptions } from "./page-layout.cjs";
+import { StaticCanvas } from "fabric";
+//#region src/pdf/export-pdf.d.ts
+/**
+ * Exports canvases and documents as PDF (fabric.js #5906), with jsPDF and
+ * svg2pdf.js as optional peer dependencies.
+ *
+ * - `vector` draws every object as PDF vectors and text, so text can be
+ *   selected and the file prints sharply at any size.
+ * - `raster` draws each page as one picture at `dpi`.
+ * - `hybrid` (the default) draws everything as vectors except what svg2pdf
+ *   cannot draw faithfully (shadows, blend modes, gradient outlines,
+ *   non-scaling outlines on scaled objects, and text in a font with no file),
+ *   which becomes a picture of just that object, in its place.
+ */
+export type PdfMode = "vector" | "raster" | "hybrid";
+/** An engine, a Fabric canvas, or a saved document or plain Fabric JSON. */
+export type PdfSource = DocumentEngine | StaticCanvas | FabricDocument | Record<string, unknown>;
+export interface PdfExportOptions extends PageLayoutOptions {
+  mode?: PdfMode;
+  /** Resolution of everything drawn as a picture. Default 300. */
+  dpi?: number;
+  /** TrueType files for the fonts the canvas uses. */
+  fonts?: PdfFont[];
+  /**
+   * Text in a font with no file in `fonts`. `rasterize` (the default in
+   * hybrid mode) draws it as a picture so it looks right; `substitute` keeps
+   * it as text in the closest built-in PDF font.
+   */
+  missingFonts?: "rasterize" | "substitute";
+  background?: ExportBackground;
+  metadata?: {
+    title?: string;
+    author?: string;
+    subject?: string;
+    keywords?: string;
+    creator?: string;
+  };
+  signal?: AbortSignal;
+  /** For documents: custom object classes, asset options and limits, as for the engine. */
+  customObjects?: CustomObjectDefinition[];
+  assets?: AssetOptions;
+  limits?: ContentLimits;
+}
+export type PdfWarningCode = "PDF_RASTERIZED" | "PDF_UNSUPPORTED" | "PDF_FONT_SUBSTITUTED" | "IMAGE_NOT_EMBEDDED";
+export interface PdfWarning {
+  code: PdfWarningCode;
+  message: string;
+  /** The page, counted from 1. */
+  page: number;
+  objectIds: string[];
+  family?: string;
+  url?: string;
+}
+export interface PdfExportResult {
+  blob: Blob;
+  pageCount: number;
+  warnings: PdfWarning[];
+}
+/**
+ * Exports one or more pages as a PDF. Each source becomes one page: an
+ * engine's canvas, a Fabric canvas, or a saved document, which is drawn on
+ * an off-screen canvas that is freed after its page.
+ */
+export declare function exportPdf(sources: PdfSource | readonly PdfSource[], options?: PdfExportOptions): Promise<PdfExportResult>;
+//#endregion

package/dist/pdf/export-pdf.d.ts

@@ -0,0 +1,73 @@
+import { FabricDocument } from "../document/document-format.js";
+import { AssetOptions } from "../assets/asset-pipeline.js";
+import { ExportBackground } from "../export/export-options.js";
+import { ContentLimits } from "../security/content-limits.js";
+import { CustomObjectDefinition } from "../fabric/object-registry.js";
+import { DocumentEngine } from "../engine/create-document-engine.js";
+import { PdfFont } from "./fonts.js";
+import { PageLayoutOptions } from "./page-layout.js";
+import { StaticCanvas } from "fabric";
+//#region src/pdf/export-pdf.d.ts
+/**
+ * Exports canvases and documents as PDF (fabric.js #5906), with jsPDF and
+ * svg2pdf.js as optional peer dependencies.
+ *
+ * - `vector` draws every object as PDF vectors and text, so text can be
+ *   selected and the file prints sharply at any size.
+ * - `raster` draws each page as one picture at `dpi`.
+ * - `hybrid` (the default) draws everything as vectors except what svg2pdf
+ *   cannot draw faithfully (shadows, blend modes, gradient outlines,
+ *   non-scaling outlines on scaled objects, and text in a font with no file),
+ *   which becomes a picture of just that object, in its place.
+ */
+export type PdfMode = "vector" | "raster" | "hybrid";
+/** An engine, a Fabric canvas, or a saved document or plain Fabric JSON. */
+export type PdfSource = DocumentEngine | StaticCanvas | FabricDocument | Record<string, unknown>;
+export interface PdfExportOptions extends PageLayoutOptions {
+  mode?: PdfMode;
+  /** Resolution of everything drawn as a picture. Default 300. */
+  dpi?: number;
+  /** TrueType files for the fonts the canvas uses. */
+  fonts?: PdfFont[];
+  /**
+   * Text in a font with no file in `fonts`. `rasterize` (the default in
+   * hybrid mode) draws it as a picture so it looks right; `substitute` keeps
+   * it as text in the closest built-in PDF font.
+   */
+  missingFonts?: "rasterize" | "substitute";
+  background?: ExportBackground;
+  metadata?: {
+    title?: string;
+    author?: string;
+    subject?: string;
+    keywords?: string;
+    creator?: string;
+  };
+  signal?: AbortSignal;
+  /** For documents: custom object classes, asset options and limits, as for the engine. */
+  customObjects?: CustomObjectDefinition[];
+  assets?: AssetOptions;
+  limits?: ContentLimits;
+}
+export type PdfWarningCode = "PDF_RASTERIZED" | "PDF_UNSUPPORTED" | "PDF_FONT_SUBSTITUTED" | "IMAGE_NOT_EMBEDDED";
+export interface PdfWarning {
+  code: PdfWarningCode;
+  message: string;
+  /** The page, counted from 1. */
+  page: number;
+  objectIds: string[];
+  family?: string;
+  url?: string;
+}
+export interface PdfExportResult {
+  blob: Blob;
+  pageCount: number;
+  warnings: PdfWarning[];
+}
+/**
+ * Exports one or more pages as a PDF. Each source becomes one page: an
+ * engine's canvas, a Fabric canvas, or a saved document, which is drawn on
+ * an off-screen canvas that is freed after its page.
+ */
+export declare function exportPdf(sources: PdfSource | readonly PdfSource[], options?: PdfExportOptions): Promise<PdfExportResult>;
+//#endregion