@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

package/dist/docx/imageParser.js

@@ -0,0 +1,522 @@
+import { findByFullName, findChild, getAttribute, getChildElements, parseNumericAttribute } from "./xmlParser.js";
+import { emuToPixels } from "../utils/units.js";
+import { WRAP_ELEMENT_NAMES, parsePositionH, parsePositionV, parseWrapElement } from "./drawingUtils.js";
+import { resolveTarget } from "./relsParser.js";
+import { isTextBoxDrawing } from "./textBoxParser.js";
+//#region src/docx/imageParser.ts
+/**
+* Convert rotation value (1/60000 of a degree) to degrees
+*
+* @param rot - Rotation in 60000ths of a degree
+* @returns Rotation in degrees
+*/
+function rotToDegrees(rot) {
+	if (!rot) return;
+	const val = Number.parseInt(rot, 10);
+	if (Number.isNaN(val)) return;
+	return val / 6e4;
+}
+/**
+* Find any of the specified elements
+*/
+function findAnyOf(parent, names) {
+	const children = getChildElements(parent);
+	for (const child of children) if (names.includes(child.name || "")) return child;
+	return null;
+}
+/**
+* Parse extent element for image size
+*
+* @param extent - wp:extent element
+* @returns ImageSize in EMUs
+*/
+function parseExtent(extent) {
+	if (!extent) return {
+		width: 0,
+		height: 0
+	};
+	return {
+		width: parseNumericAttribute(extent, null, "cx") ?? 0,
+		height: parseNumericAttribute(extent, null, "cy") ?? 0
+	};
+}
+/**
+* Parse effect extent for shadow/effect margins
+*
+* @param effectExtent - wp:effectExtent element
+* @returns Padding for effects
+*/
+function parseEffectExtent(effectExtent) {
+	if (!effectExtent) return;
+	const l = parseNumericAttribute(effectExtent, null, "l") ?? 0;
+	const t = parseNumericAttribute(effectExtent, null, "t") ?? 0;
+	const r = parseNumericAttribute(effectExtent, null, "r") ?? 0;
+	const b = parseNumericAttribute(effectExtent, null, "b") ?? 0;
+	if (l === 0 && t === 0 && r === 0 && b === 0) return;
+	return {
+		left: l,
+		top: t,
+		right: r,
+		bottom: b
+	};
+}
+/**
+* Parse document properties (wp:docPr)
+*
+* @param docPr - wp:docPr element
+* @returns Object with id, name, description, title
+*/
+function parseDocProps(docPr) {
+	if (!docPr) return {};
+	const id = getAttribute(docPr, null, "id");
+	const name = getAttribute(docPr, null, "name");
+	const descr = getAttribute(docPr, null, "descr");
+	const title = getAttribute(docPr, null, "title");
+	const decorative = getAttribute(docPr, null, "decorative") === "1";
+	const hlinkClickEl = findChild(docPr, "a", "hlinkClick");
+	const hlinkRId = hlinkClickEl ? getAttribute(hlinkClickEl, "r", "id") : null;
+	return {
+		...id != null ? { id } : {},
+		...name != null ? { name } : {},
+		...descr != null ? { alt: descr } : {},
+		...title != null ? { title } : {},
+		...decorative ? { decorative } : {},
+		...hlinkRId != null ? { hlinkRId } : {}
+	};
+}
+/**
+* Parse transform properties from a:xfrm
+*/
+function parseTransform(xfrm) {
+	if (!xfrm) return;
+	const rot = getAttribute(xfrm, null, "rot");
+	const flipH = getAttribute(xfrm, null, "flipH") === "1";
+	const flipV = getAttribute(xfrm, null, "flipV") === "1";
+	const rotation = rotToDegrees(rot);
+	if (rotation === void 0 && !flipH && !flipV) return;
+	const transform = {};
+	if (rotation !== void 0) transform.rotation = rotation;
+	if (flipH) transform.flipH = true;
+	if (flipV) transform.flipV = true;
+	return transform;
+}
+/**
+* Find the pic:blipFill element in a w:drawing container.
+*
+* Path: a:graphic > a:graphicData > pic:pic > pic:blipFill
+*
+* The blipFill carries both `a:blip` (the relationship ID) and the optional
+* `a:srcRect` crop element, so callers that need either share this walk.
+*/
+function findBlipFillElement(container) {
+	const graphic = findByFullName(container, "a:graphic");
+	if (!graphic) return null;
+	const graphicData = findByFullName(graphic, "a:graphicData");
+	if (!graphicData) return null;
+	const pic = findByFullName(graphicData, "pic:pic");
+	if (!pic) return null;
+	return findByFullName(pic, "pic:blipFill");
+}
+/**
+* Parse `<a:srcRect l="..." t="..." r="..." b="..."/>` inside `pic:blipFill`.
+* Values are in 1/100000 of the source image dimension; converted to fractions
+* in [0, 1] so the renderer can apply them as CSS clip-path percentages.
+*
+* eigenpal #424 (image-crop subset).
+*/
+function parseImageCrop(blipFill) {
+	if (!blipFill) return;
+	const srcRect = findByFullName(blipFill, "a:srcRect");
+	if (!srcRect) return;
+	const toFraction = (attr) => {
+		const raw = parseNumericAttribute(srcRect, null, attr);
+		if (raw === void 0 || raw === 0) return;
+		return raw / 1e5;
+	};
+	const left = toFraction("l");
+	const top = toFraction("t");
+	const right = toFraction("r");
+	const bottom = toFraction("b");
+	if (left === void 0 && top === void 0 && right === void 0 && bottom === void 0) return;
+	const crop = {};
+	if (left !== void 0) crop.left = left;
+	if (top !== void 0) crop.top = top;
+	if (right !== void 0) crop.right = right;
+	if (bottom !== void 0) crop.bottom = bottom;
+	return crop;
+}
+/**
+* Parse an OOXML `ST_OnOff` attribute on an element. Accepts the full
+* set of literals the spec allows (`"1"`/`"true"`/`"on"` and
+* `"0"`/`"false"`/`"off"`); anything else (including an absent
+* attribute) folds back to `undefined` so callers can apply the
+* spec-defined default.
+*/
+function parseOnOffAttr(element, name) {
+	const raw = getAttribute(element, null, name);
+	if (raw === null) return;
+	if (raw === "1" || raw === "true" || raw === "on") return true;
+	if (raw === "0" || raw === "false" || raw === "off") return false;
+}
+/**
+* Parse `<a:alphaModFix amt="..."/>` inside the `a:blip` element. The
+* `amt` value is in 1/100000; convert to a fraction in [0, 1] for CSS
+* `opacity`. Returns undefined when no alpha modifier is present (fully
+* opaque), when `amt` is missing or non-numeric, or when `amt` >= 100000
+* (also fully opaque). `parseNumericAttribute` already returns
+* `undefined` (not `NaN`) for non-numeric values, so a downstream NaN
+* is impossible here.
+*
+* Mirrors eigenpal docx-editor #424.
+*/
+function parseImageOpacity(blip) {
+	if (!blip) return;
+	const alpha = findByFullName(blip, "a:alphaModFix");
+	if (!alpha) return;
+	const amt = parseNumericAttribute(alpha, null, "amt");
+	if (amt === void 0 || amt >= 1e5) return;
+	return Math.max(0, amt / 1e5);
+}
+/**
+* Extract rId from a:blip element
+*/
+function extractBlipRId(blip) {
+	if (!blip) return "";
+	const rEmbed = getAttribute(blip, "r", "embed");
+	if (rEmbed) return rEmbed;
+	const embed = getAttribute(blip, null, "embed");
+	if (embed) return embed;
+	const rLink = getAttribute(blip, "r", "link");
+	if (rLink) return rLink;
+	return "";
+}
+/**
+* Find transform (a:xfrm) from picture shape properties
+*
+* Path: a:graphic > a:graphicData > pic:pic > pic:spPr > a:xfrm
+*/
+function findPictureTransform(container) {
+	const graphic = findByFullName(container, "a:graphic");
+	if (!graphic) return null;
+	const graphicData = findByFullName(graphic, "a:graphicData");
+	if (!graphicData) return null;
+	const pic = findByFullName(graphicData, "pic:pic");
+	if (!pic) return null;
+	const spPr = findByFullName(pic, "pic:spPr");
+	if (!spPr) return null;
+	return findByFullName(spPr, "a:xfrm");
+}
+/**
+* Normalize a target path to the standard word/media/... format
+*/
+function normalizeMediaPath(targetPath) {
+	if (!targetPath) return targetPath;
+	let normalized = targetPath.replace(/^\/+/u, "");
+	if (!normalized.startsWith("word/")) normalized = `word/${normalized}`;
+	return normalized;
+}
+/**
+* Get MIME type from file extension
+*/
+function getMimeType(path) {
+	return {
+		png: "image/png",
+		jpg: "image/jpeg",
+		jpeg: "image/jpeg",
+		gif: "image/gif",
+		bmp: "image/bmp",
+		tiff: "image/tiff",
+		tif: "image/tiff",
+		webp: "image/webp",
+		svg: "image/svg+xml",
+		emf: "image/x-emf",
+		wmf: "image/x-wmf"
+	}[path.split(".").pop()?.toLowerCase() ?? ""] ?? "application/octet-stream";
+}
+/**
+* Resolve image data from relationships and media map
+*
+* @param rId - Relationship ID (e.g., "rId1")
+* @param rels - Relationship map
+* @param media - Media files map
+* @returns Object with src (data URL or blob), mimeType, and filename
+*/
+function resolveImageData(rId, rels, media) {
+	if (!rId || !rels) return {};
+	const rel = rels.get(rId);
+	if (!rel) return {};
+	const targetPath = rel.target;
+	if (!targetPath) return {};
+	const normalizedPath = normalizeMediaPath(targetPath);
+	const filename = targetPath.split("/").pop();
+	const findMediaCaseInsensitive = (map, searchPath) => {
+		const lowerPath = searchPath.toLowerCase();
+		for (const [key, value] of map.entries()) if (key.toLowerCase() === lowerPath) return value;
+	};
+	if (media) {
+		const mediaFile = findMediaCaseInsensitive(media, normalizedPath);
+		if (mediaFile) {
+			const src = mediaFile.dataUrl || mediaFile.base64;
+			return {
+				...src !== void 0 ? { src } : {},
+				mimeType: mediaFile.mimeType,
+				...filename !== void 0 ? { filename } : {}
+			};
+		}
+		const altPath = targetPath.replace(/^\/+/u, "");
+		const altMediaFile = findMediaCaseInsensitive(media, altPath);
+		if (altMediaFile) {
+			const src = altMediaFile.dataUrl || altMediaFile.base64;
+			return {
+				...src !== void 0 ? { src } : {},
+				mimeType: altMediaFile.mimeType,
+				...filename !== void 0 ? { filename } : {}
+			};
+		}
+		const prefixedMediaFile = findMediaCaseInsensitive(media, `word/${altPath}`);
+		if (prefixedMediaFile) {
+			const src = prefixedMediaFile.dataUrl || prefixedMediaFile.base64;
+			return {
+				...src !== void 0 ? { src } : {},
+				mimeType: prefixedMediaFile.mimeType,
+				...filename !== void 0 ? { filename } : {}
+			};
+		}
+	}
+	return {
+		mimeType: getMimeType(targetPath),
+		...filename !== void 0 ? { filename } : {}
+	};
+}
+/**
+* Parse a wp:inline element (inline image)
+*
+* @param inlineEl - The wp:inline element
+* @param rels - Relationship map for resolving rId
+* @param media - Media files map
+* @returns Parsed Image object
+*/
+function parseInline(inlineEl, rels, media) {
+	const size = parseExtent(findByFullName(inlineEl, "wp:extent"));
+	const padding = parseEffectExtent(findByFullName(inlineEl, "wp:effectExtent"));
+	const props = parseDocProps(findByFullName(inlineEl, "wp:docPr"));
+	const blipFill = findBlipFillElement(inlineEl);
+	const blip = blipFill ? findByFullName(blipFill, "a:blip") : null;
+	const rId = extractBlipRId(blip);
+	const crop = parseImageCrop(blipFill);
+	const opacity = parseImageOpacity(blip);
+	const imageData = resolveImageData(rId, rels, media);
+	const transform = parseTransform(findPictureTransform(inlineEl));
+	const distT = parseNumericAttribute(inlineEl, null, "distT") ?? void 0;
+	const distB = parseNumericAttribute(inlineEl, null, "distB") ?? void 0;
+	const distL = parseNumericAttribute(inlineEl, null, "distL") ?? void 0;
+	const distR = parseNumericAttribute(inlineEl, null, "distR") ?? void 0;
+	const wrap = { type: "inline" };
+	if (distT !== void 0) wrap.distT = distT;
+	if (distB !== void 0) wrap.distB = distB;
+	if (distL !== void 0) wrap.distL = distL;
+	if (distR !== void 0) wrap.distR = distR;
+	const image = {
+		type: "image",
+		rId,
+		size,
+		wrap
+	};
+	if (props.id) image.id = props.id;
+	if (props.alt) image.alt = props.alt;
+	if (props.title) image.title = props.title;
+	if (props.decorative) image.decorative = true;
+	if (imageData.src) image.src = imageData.src;
+	if (imageData.mimeType) image.mimeType = imageData.mimeType;
+	if (imageData.filename) image.filename = imageData.filename;
+	if (padding) image.padding = padding;
+	if (transform) image.transform = transform;
+	if (crop) image.crop = crop;
+	if (opacity !== void 0) image.opacity = opacity;
+	if (props.hlinkRId && rels) {
+		const href = resolveTarget(rels, props.hlinkRId);
+		if (href) image.hlinkHref = href;
+	}
+	return image;
+}
+/**
+* Parse a wp:anchor element (floating/anchored image)
+*
+* @param anchorEl - The wp:anchor element
+* @param rels - Relationship map for resolving rId
+* @param media - Media files map
+* @returns Parsed Image object
+*/
+function parseAnchor(anchorEl, rels, media) {
+	const size = parseExtent(findByFullName(anchorEl, "wp:extent"));
+	const padding = parseEffectExtent(findByFullName(anchorEl, "wp:effectExtent"));
+	const props = parseDocProps(findByFullName(anchorEl, "wp:docPr"));
+	const behindDoc = getAttribute(anchorEl, null, "behindDoc") === "1";
+	const layoutInCell = parseOnOffAttr(anchorEl, "layoutInCell");
+	const allowOverlap = parseOnOffAttr(anchorEl, "allowOverlap");
+	const anchorDistT = parseNumericAttribute(anchorEl, null, "distT");
+	const anchorDistB = parseNumericAttribute(anchorEl, null, "distB");
+	const anchorDistL = parseNumericAttribute(anchorEl, null, "distL");
+	const anchorDistR = parseNumericAttribute(anchorEl, null, "distR");
+	const anchorDistances = {
+		...anchorDistT != null ? { distT: anchorDistT } : {},
+		...anchorDistB != null ? { distB: anchorDistB } : {},
+		...anchorDistL != null ? { distL: anchorDistL } : {},
+		...anchorDistR != null ? { distR: anchorDistR } : {}
+	};
+	const wrap = parseWrapElement(findAnyOf(anchorEl, WRAP_ELEMENT_NAMES), behindDoc, anchorDistances);
+	const posH = findByFullName(anchorEl, "wp:positionH");
+	const posV = findByFullName(anchorEl, "wp:positionV");
+	const horizontal = parsePositionH(posH);
+	const vertical = parsePositionV(posV);
+	let position;
+	if (horizontal || vertical) position = {
+		horizontal: horizontal ?? { relativeTo: "column" },
+		vertical: vertical ?? { relativeTo: "paragraph" }
+	};
+	const blipFill = findBlipFillElement(anchorEl);
+	const blip = blipFill ? findByFullName(blipFill, "a:blip") : null;
+	const rId = extractBlipRId(blip);
+	const crop = parseImageCrop(blipFill);
+	const opacity = parseImageOpacity(blip);
+	const imageData = resolveImageData(rId, rels, media);
+	const transform = parseTransform(findPictureTransform(anchorEl));
+	const image = {
+		type: "image",
+		rId,
+		size,
+		wrap
+	};
+	if (props.id) image.id = props.id;
+	if (props.alt) image.alt = props.alt;
+	if (props.title) image.title = props.title;
+	if (props.decorative) image.decorative = true;
+	if (imageData.src) image.src = imageData.src;
+	if (imageData.mimeType) image.mimeType = imageData.mimeType;
+	if (imageData.filename) image.filename = imageData.filename;
+	if (position) image.position = position;
+	if (padding) image.padding = padding;
+	if (transform) image.transform = transform;
+	if (crop) image.crop = crop;
+	if (opacity !== void 0) image.opacity = opacity;
+	if (layoutInCell !== void 0) image.layoutInCell = layoutInCell;
+	if (allowOverlap !== void 0) image.allowOverlap = allowOverlap;
+	if (props.hlinkRId && rels) {
+		const href = resolveTarget(rels, props.hlinkRId);
+		if (href) image.hlinkHref = href;
+	}
+	return image;
+}
+/**
+* Parse a w:drawing element
+*
+* The drawing element contains either wp:inline or wp:anchor.
+*
+* @param drawingEl - The w:drawing element
+* @param rels - Relationship map for resolving rId
+* @param media - Media files map
+* @returns Parsed Image object or null if not an image
+*/
+function parseDrawing(drawingEl, rels, media) {
+	if (isTextBoxDrawing(drawingEl)) return null;
+	const children = getChildElements(drawingEl);
+	for (const child of children) {
+		const name = child.name || "";
+		if (name === "wp:inline" || name === "wp:anchor") return name === "wp:inline" ? parseInline(child, rels, media) : parseAnchor(child, rels, media);
+	}
+	return null;
+}
+/**
+* Parse an image from a w:drawing element
+*
+* This is the main entry point for image parsing.
+*
+* @param node - The w:drawing XML element
+* @param rels - Relationship map for resolving rId
+* @param media - Media files map
+* @returns Parsed Image object or null if parsing fails
+*/
+function parseImage(node, rels, media) {
+	return parseDrawing(node, rels, media);
+}
+/**
+* Check if an image is inline (not floating)
+*/
+function isInlineImage(image) {
+	return image.wrap.type === "inline";
+}
+/**
+* Check if an image is floating (anchored)
+*/
+function isFloatingImage(image) {
+	return image.wrap.type !== "inline";
+}
+/**
+* Check if an image is behind text
+*/
+function isBehindText(image) {
+	return image.wrap.type === "behind";
+}
+/**
+* Check if an image is in front of text
+*/
+function isInFrontOfText(image) {
+	return image.wrap.type === "inFront";
+}
+/**
+* Get image width in pixels
+*/
+function getImageWidthPx(image) {
+	return emuToPixels(image.size.width);
+}
+/**
+* Get image height in pixels
+*/
+function getImageHeightPx(image) {
+	return emuToPixels(image.size.height);
+}
+/**
+* Get image dimensions in pixels
+*/
+function getImageDimensionsPx(image) {
+	return {
+		width: emuToPixels(image.size.width),
+		height: emuToPixels(image.size.height)
+	};
+}
+/**
+* Check if image has alt text (for accessibility)
+*/
+function hasAltText(image) {
+	return !!image.alt && image.alt.trim().length > 0;
+}
+/**
+* Check if image is decorative (should be ignored by screen readers)
+*/
+function isDecorativeImage(image) {
+	return image.decorative === true;
+}
+/**
+* Get wrap distances in pixels
+*/
+function getWrapDistancesPx(image) {
+	return {
+		top: emuToPixels(image.wrap.distT),
+		bottom: emuToPixels(image.wrap.distB),
+		left: emuToPixels(image.wrap.distL),
+		right: emuToPixels(image.wrap.distR)
+	};
+}
+/**
+* Check if image needs text wrapping
+*/
+function needsTextWrapping(image) {
+	return [
+		"square",
+		"tight",
+		"through",
+		"topAndBottom"
+	].includes(image.wrap.type);
+}
+//#endregion
+export { getImageDimensionsPx, getImageHeightPx, getImageWidthPx, getWrapDistancesPx, hasAltText, isBehindText, isDecorativeImage, isFloatingImage, isInFrontOfText, isInlineImage, needsTextWrapping, parseDrawing, parseImage, resolveImageData };

package/dist/docx/mathToMathml.d.ts

@@ -0,0 +1,15 @@
+import { XmlElement } from "./xmlParser.js";
+
+//#region src/docx/mathToMathml.d.ts
+/**
+ * Convert an OMML element (`<m:oMath>` or `<m:oMathPara>`) into a MathML
+ * XML string.
+ *
+ * The returned string is the full `<math>...</math>` element including the
+ * MathML namespace, ready to set via `Element.innerHTML` or
+ * `Range.createContextualFragment`. Returns `null` if `omml` is not an
+ * OMML root element or contains no convertible children.
+ */
+declare function ommlToMathml(omml: XmlElement): string | null;
+//#endregion
+export { ommlToMathml };