@stll/folio-core 0.29.0 → 0.31.0

package/dist/docx/vmlImageParser.js

@@ -1,113 +1,71 @@
 import { sanitizeImageSrc } from "../utils/sanitizeImageSrc.js";
 import { pixelsToEmu } from "../utils/units.js";
 import { resolveImageData } from "./imageParser.js";
+import { isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl } from "./vmlPreview.js";
 import { isWatermarkShape } from "./watermarkParser.js";
-import { cloneWithXmlnsDeclarations, elementToXml, findAllDeep, findChild, findDeep, getAttribute, getChildElements, getLocalName } from "./xmlParser.js";
+import { cloneWithXmlnsDeclarations, elementToXml, findAllDeep, findChild, getAttribute, getChildElements, getLocalName } from "./xmlParser.js";
 //#region src/docx/vmlImageParser.ts
-const MAX_VML_PREVIEW_SHAPES = 256;
-const MAX_VML_PREVIEW_DIMENSION_PX = 2e4;
-const MAX_VML_SVG_CHARACTERS = 1e6;
-const SAFE_VML_COLORS = /* @__PURE__ */ new Set([
-	"black",
-	"white",
-	"red",
-	"green",
-	"blue",
-	"yellow",
-	"gray",
-	"grey",
-	"silver",
-	"maroon",
-	"purple",
-	"fuchsia",
-	"lime",
-	"olive",
-	"navy",
-	"teal",
-	"aqua"
-]);
-/**
-* Convert a CSS length (pt/in/px/cm/mm/pc, default px) to pixels. Units are
-* matched case-insensitively (`2IN`, `2Pt` are valid VML). The numeric part
-* must be a single well-formed decimal, so malformed input like `1.2.3` is
-* rejected rather than truncated to `1.2`.
-*/
-function cssLengthToPx(raw) {
-	if (!raw) return;
-	const match = /^(?<amount>-?(?:\d+(?:\.\d+)?|\.\d+))\s*(?<unit>pt|in|px|cm|mm|pc)?$/iu.exec(raw.trim());
-	const amountText = match?.groups?.["amount"];
-	if (amountText === void 0) return;
-	const value = Number.parseFloat(amountText);
-	if (Number.isNaN(value)) return;
-	switch (match?.groups?.["unit"]?.toLowerCase()) {
-		case "pt": return value / 72 * 96;
-		case "in": return value * 96;
-		case "cm": return value / 2.54 * 96;
-		case "mm": return value / 25.4 * 96;
-		case "pc": return value / 6 * 96;
-		case "px":
-		case void 0: return value;
-		default: return;
+const VML_POSITION_ABSOLUTE = "absolute";
+const IMAGE_WRAP_INLINE = "inline";
+const IMAGE_WRAP_BEHIND = "behind";
+const IMAGE_WRAP_IN_FRONT = "inFront";
+const pixelsToSafeEmu = (pixels) => {
+	const emu = pixelsToEmu(pixels);
+	return Number.isSafeInteger(emu) ? emu : void 0;
+};
+const horizontalRelativeTo = (value) => {
+	switch (value?.toLowerCase()) {
+		case "char": return "character";
+		case "text": return "column";
+		case "margin": return "margin";
+		case "page": return "page";
+		case "left-margin-area": return "leftMargin";
+		case "right-margin-area": return "rightMargin";
+		case "inner-margin-area": return "insideMargin";
+		case "outer-margin-area": return "outsideMargin";
+		default: return "character";
 	}
-}
-const PROTOTYPE_POLLUTION_KEYS = /* @__PURE__ */ new Set([
-	"__proto__",
-	"constructor",
-	"prototype"
-]);
-/** Read a `style="k1:v1;k2:v2"` attribute into a lowercased key/value record. */
-function parseStyleAttr(style) {
-	const out = Object.create(null);
-	if (!style) return out;
-	for (const decl of style.split(";")) {
-		const colon = decl.indexOf(":");
-		if (colon < 0) continue;
-		const key = decl.slice(0, colon).trim().toLowerCase();
-		const value = decl.slice(colon + 1).trim();
-		if (!key || PROTOTYPE_POLLUTION_KEYS.has(key)) continue;
-		out[key] = value;
+};
+const verticalRelativeTo = (value) => {
+	switch (value?.toLowerCase()) {
+		case "line": return "line";
+		case "text": return "paragraph";
+		case "margin": return "margin";
+		case "page": return "page";
+		case "top-margin-area": return "topMargin";
+		case "bottom-margin-area": return "bottomMargin";
+		case "inner-margin-area": return "insideMargin";
+		case "outer-margin-area": return "outsideMargin";
+		default: return "paragraph";
 	}
-	return out;
-}
-const finiteNumber = (raw) => {
-	if (!raw || !/^-?(?:\d+(?:\.\d+)?|\.\d+)$/u.test(raw.trim())) return;
-	const value = Number.parseFloat(raw);
-	return Number.isFinite(value) ? value : void 0;
 };
-const coordinatePair = (raw) => {
-	const [firstRaw, secondRaw, extra] = raw?.split(",").map((part) => part.trim()) ?? [];
-	if (extra !== void 0) return;
-	const first = finiteNumber(firstRaw);
-	const second = finiteNumber(secondRaw);
-	return first === void 0 || second === void 0 ? void 0 : {
-		first,
-		second
+const vmlImageLayout = (style) => {
+	if (style["position"]?.toLowerCase() !== VML_POSITION_ABSOLUTE) return { wrap: { type: IMAGE_WRAP_INLINE } };
+	const leftPx = vmlCssLengthToPx(style["margin-left"] ?? style["left"]) ?? 0;
+	const topPx = vmlCssLengthToPx(style["margin-top"] ?? style["top"]) ?? 0;
+	const zIndex = parseVmlNumber(style["z-index"]);
+	return {
+		wrap: { type: zIndex !== void 0 && zIndex < 0 ? IMAGE_WRAP_BEHIND : IMAGE_WRAP_IN_FRONT },
+		position: {
+			horizontal: {
+				relativeTo: horizontalRelativeTo(style["mso-position-horizontal-relative"]),
+				posOffset: pixelsToSafeEmu(leftPx) ?? 0
+			},
+			vertical: {
+				relativeTo: verticalRelativeTo(style["mso-position-vertical-relative"]),
+				posOffset: pixelsToSafeEmu(topPx) ?? 0
+			}
+		}
 	};
 };
-const safeColor = (raw, fallback) => {
-	const normalized = raw?.trim().toLowerCase();
-	if (!normalized) return fallback;
-	if (SAFE_VML_COLORS.has(normalized)) return normalized;
-	if (/^#[0-9a-f]{3}(?:[0-9a-f]{3})?$/u.test(normalized)) return normalized;
-	return /^[0-9a-f]{6}$/u.test(normalized) ? `#${normalized}` : fallback;
-};
-const validPreviewDimension = (value) => value !== void 0 && value > 0 && value <= MAX_VML_PREVIEW_DIMENSION_PX;
-const svgDataUrl = (svg) => svg.length <= MAX_VML_SVG_CHARACTERS ? `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}` : void 0;
-const vmlShapeSvg = (shape, width, height, x = 0, y = 0) => {
-	const fill = safeColor(getAttribute(shape, null, "fillcolor"), "white");
-	const stroke = getAttribute(shape, null, "stroked")?.toLowerCase() !== "f" ? safeColor(getAttribute(shape, null, "strokecolor"), "black") : "none";
-	const localName = getLocalName(shape.name ?? "");
-	if (localName === "oval") return `<ellipse cx="${x + width / 2}" cy="${y + height / 2}" rx="${width / 2}" ry="${height / 2}" fill="${fill}" stroke="${stroke}"/>`;
-	return `<rect x="${x}" y="${y}" width="${width}" height="${height}" rx="${localName === "roundrect" ? Math.min(width, height) * .1 : 0}" fill="${fill}" stroke="${stroke}"/>`;
-};
 const previewImage = (pictElement, svg, widthPx, heightPx, style, rootXmlns) => {
-	const src = svgDataUrl(svg);
+	const src = vmlSvgDataUrl(svg);
 	if (!src) return null;
-	const leftPx = cssLengthToPx(style["margin-left"] ?? style["left"]) ?? 0;
-	const topPx = cssLengthToPx(style["margin-top"] ?? style["top"]) ?? 0;
+	const leftPx = vmlCssLengthToPx(style["margin-left"] ?? style["left"]) ?? 0;
+	const topPx = vmlCssLengthToPx(style["margin-top"] ?? style["top"]) ?? 0;
 	const horizontalRelative = style["mso-position-horizontal-relative"] === "page";
 	const verticalRelative = style["mso-position-vertical-relative"] === "page";
-	const zIndex = finiteNumber(style["z-index"]);
+	const zIndex = parseVmlNumber(style["z-index"]);
 	return {
 		type: "drawing",
 		image: {
@@ -124,62 +82,24 @@ const previewImage = (pictElement, svg, widthPx, heightPx, style, rootXmlns) =>
 			position: {
 				horizontal: {
 					relativeTo: horizontalRelative ? "page" : "character",
-					posOffset: pixelsToEmu(leftPx)
+					posOffset: pixelsToSafeEmu(leftPx) ?? 0
 				},
 				vertical: {
 					relativeTo: verticalRelative ? "page" : "paragraph",
-					posOffset: pixelsToEmu(topPx)
+					posOffset: pixelsToSafeEmu(topPx) ?? 0
 				}
 			}
 		},
 		rawXml: elementToXml(cloneWithXmlnsDeclarations(pictElement, rootXmlns))
 	};
 };
-const parseStandaloneShapePreview = (pictElement, shape, rootXmlns) => {
-	if (findDeep(shape, "v", "textbox")) return null;
-	const style = parseStyleAttr(getAttribute(shape, null, "style"));
-	const widthPx = cssLengthToPx(style["width"]);
-	const heightPx = cssLengthToPx(style["height"]);
-	if (!validPreviewDimension(widthPx) || !validPreviewDimension(heightPx)) return null;
-	const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${widthPx} ${heightPx}" width="${widthPx}" height="${heightPx}">${vmlShapeSvg(shape, widthPx, heightPx)}</svg>`;
-	return previewImage(pictElement, svg, widthPx, heightPx, style, rootXmlns);
-};
-const parseGroupPreview = (pictElement, group, rootXmlns) => {
-	const style = parseStyleAttr(getAttribute(group, null, "style"));
-	const widthPx = cssLengthToPx(style["width"]);
-	const heightPx = cssLengthToPx(style["height"]);
-	if (!validPreviewDimension(widthPx) || !validPreviewDimension(heightPx)) return null;
-	const origin = coordinatePair(getAttribute(group, null, "coordorigin")) ?? {
-		first: 0,
-		second: 0
-	};
-	const size = coordinatePair(getAttribute(group, null, "coordsize")) ?? {
-		first: widthPx,
-		second: heightPx
-	};
-	if (size.first <= 0 || size.second <= 0) return null;
-	const content = getChildElements(group).slice(0, MAX_VML_PREVIEW_SHAPES).map((child) => {
-		const localName = getLocalName(child.name ?? "");
-		if (findDeep(child, "v", "textbox")) return "";
-		if (localName === "line") {
-			const from = coordinatePair(getAttribute(child, null, "from"));
-			const to = coordinatePair(getAttribute(child, null, "to"));
-			if (!from || !to) return "";
-			const stroke = safeColor(getAttribute(child, null, "strokecolor"), "black");
-			return `<line x1="${from.first}" y1="${from.second}" x2="${to.first}" y2="${to.second}" stroke="${stroke}"/>`;
-		}
-		if (localName !== "rect" && localName !== "roundrect" && localName !== "oval") return "";
-		const childStyle = parseStyleAttr(getAttribute(child, null, "style"));
-		const x = finiteNumber(childStyle["left"]);
-		const y = finiteNumber(childStyle["top"]);
-		const width = finiteNumber(childStyle["width"]);
-		const height = finiteNumber(childStyle["height"]);
-		if (x === void 0 || y === void 0 || width === void 0 || height === void 0) return "";
-		return vmlShapeSvg(child, width, height, x, y);
-	}).join("");
-	if (!content) return null;
-	const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${origin.first} ${origin.second} ${size.first} ${size.second}" width="${widthPx}" height="${heightPx}">${content}</svg>`;
-	return previewImage(pictElement, svg, widthPx, heightPx, style, rootXmlns);
+const previewDrawing = (pictElement, preview, rootXmlns) => {
+	switch (preview.type) {
+		case "rendered": return previewImage(pictElement, preview.svg, preview.widthPx, preview.heightPx, preview.style, rootXmlns);
+		case "empty":
+		case "invalid": return null;
+		default: return preview;
+	}
 };
 /**
 * Read the relationship id off a `v:imagedata` element. Word writes `r:id`;
@@ -212,18 +132,18 @@ function parseVmlImageContent(pictElement, rels, media, rootXmlns = {}) {
 		if (!rId) continue;
 		if (isWatermarkShape(shape)) continue;
 		const { src, mimeType, filename } = resolveImageData(rId, rels ?? void 0, media ?? void 0);
-		const shapeStyle = parseStyleAttr(getAttribute(shape, null, "style"));
-		const widthPx = cssLengthToPx(shapeStyle["width"]);
-		const heightPx = cssLengthToPx(shapeStyle["height"]);
-		if (getLocalName(pictElement.name ?? "") === "object" && (widthPx !== void 0 && !validPreviewDimension(widthPx) || heightPx !== void 0 && !validPreviewDimension(heightPx))) continue;
+		const shapeStyle = parseVmlStyle(getAttribute(shape, null, "style"));
+		const widthPx = vmlCssLengthToPx(shapeStyle["width"]);
+		const heightPx = vmlCssLengthToPx(shapeStyle["height"]);
+		if (getLocalName(pictElement.name ?? "") === "object" && (widthPx !== void 0 && !isValidVmlPreviewDimension(widthPx) || heightPx !== void 0 && !isValidVmlPreviewDimension(heightPx))) continue;
 		const image = {
 			type: "image",
 			rId,
 			size: {
-				width: widthPx != null ? pixelsToEmu(widthPx) : 0,
-				height: heightPx != null ? pixelsToEmu(heightPx) : 0
+				width: widthPx != null ? pixelsToSafeEmu(widthPx) ?? 0 : 0,
+				height: heightPx != null ? pixelsToSafeEmu(heightPx) ?? 0 : 0
 			},
-			wrap: { type: "inline" }
+			...vmlImageLayout(shapeStyle)
 		};
 		const safeSrc = sanitizeImageSrc(src);
 		if (safeSrc) image.src = safeSrc;
@@ -240,12 +160,12 @@ function parseVmlImageContent(pictElement, rels, media, rootXmlns = {}) {
 	for (const child of getChildElements(pictElement)) {
 		const localName = getLocalName(child.name ?? "");
 		if (localName === "group") {
-			const preview = parseGroupPreview(pictElement, child, rootXmlns);
+			const preview = previewDrawing(pictElement, renderVmlGroupPreview(child), rootXmlns);
 			if (preview) return preview;
 			continue;
 		}
 		if (localName === "rect" || localName === "roundrect" || localName === "oval") {
-			const preview = parseStandaloneShapePreview(pictElement, child, rootXmlns);
+			const preview = previewDrawing(pictElement, renderStandaloneVmlPreview(child), rootXmlns);
 			if (preview) return preview;
 		}
 	}

package/dist/docx/vmlPreview.d.ts

@@ -0,0 +1,31 @@
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/vmlPreview.d.ts
+type VmlPreviewResult = {
+  type: "rendered";
+  svg: string;
+  widthPx: number;
+  heightPx: number;
+  style: Record<string, string>;
+} | {
+  type: "empty";
+} | {
+  type: "invalid";
+};
+/** Parse a VML/CSS length into CSS pixels without accepting partial numbers. */
+declare const vmlCssLengthToPx: (raw: string | undefined) => number | undefined;
+/** Read a VML `style` attribute into a prototype-free lowercased record. */
+declare const parseVmlStyle: (style: string | null) => Record<string, string>;
+/** Parse a finite VML number without exponent or partial-number coercion. */
+declare const parseVmlNumber: (raw: string | null | undefined) => number | undefined;
+/** Check a physical preview dimension against the retained SVG layout bound. */
+declare const isValidVmlPreviewDimension: (value: number | undefined) => value is number;
+/** Encode a generated, already-sanitized SVG without exceeding its output cap. */
+declare const vmlSvgDataUrl: (svg: string) => string | undefined;
+/** Render a bounded standalone VML rectangle or oval preview. */
+declare const renderStandaloneVmlPreview: (shape: XmlElement) => VmlPreviewResult;
+/** Render a VML group through bounded, non-clipping local-coordinate transforms. */
+declare const renderVmlGroupPreview: (group: XmlElement) => VmlPreviewResult;
+/** Bound retained synthetic VML previews while preserving their raw replay nodes. */
+declare const enforcePackageVmlPreviewBudget: (root: unknown, maxCharacters?: number) => void;
+//#endregion
+export { VmlPreviewResult, enforcePackageVmlPreviewBudget, isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl };