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

package/dist/docx/headerFooterRefParser.js

@@ -0,0 +1,52 @@
+import { findChildren, getAttribute } from "./xmlParser.js";
+//#region src/docx/headerFooterRefParser.ts
+/**
+* Parse header type attribute
+*/
+function parseHeaderFooterType(typeAttr) {
+	switch (typeAttr) {
+		case "first": return "first";
+		case "even": return "even";
+		default: return "default";
+	}
+}
+function parseHeaderFooterReference(element) {
+	const typeAttr = getAttribute(element, "w", "type");
+	const rId = getAttribute(element, "r", "id") ?? "";
+	return {
+		type: parseHeaderFooterType(typeAttr),
+		rId
+	};
+}
+/**
+* Parse a header reference from sectPr (w:headerReference)
+*/
+function parseHeaderReference(element) {
+	return parseHeaderFooterReference(element);
+}
+/**
+* Parse a footer reference from sectPr (w:footerReference)
+*/
+function parseFooterReference(element) {
+	return parseHeaderFooterReference(element);
+}
+/**
+* Parse all header references from a sectPr element
+*/
+function parseHeaderReferences(sectPr) {
+	const refs = [];
+	const headerRefElements = findChildren(sectPr, "w", "headerReference");
+	for (const el of headerRefElements) refs.push(parseHeaderReference(el));
+	return refs;
+}
+/**
+* Parse all footer references from a sectPr element
+*/
+function parseFooterReferences(sectPr) {
+	const refs = [];
+	const footerRefElements = findChildren(sectPr, "w", "footerReference");
+	for (const el of footerRefElements) refs.push(parseFooterReference(el));
+	return refs;
+}
+//#endregion
+export { parseFooterReference, parseFooterReferences, parseHeaderReference, parseHeaderReferences };

package/dist/docx/headerFooterReferenceNormalization.d.ts

@@ -0,0 +1,19 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/docx/headerFooterReferenceNormalization.d.ts
+type NormalizeHeaderFooterReferencesInput = {
+  documentBody: document_d_exports.DocumentBody;
+  headers?: Map<string, document_d_exports.HeaderFooter>;
+  footers?: Map<string, document_d_exports.HeaderFooter>;
+};
+type NormalizeHeaderFooterReferencesResult = {
+  removedDanglingHeaderReferences: number;
+  removedDanglingFooterReferences: number;
+};
+declare const normalizeHeaderFooterReferences: ({
+  documentBody,
+  headers,
+  footers
+}: NormalizeHeaderFooterReferencesInput) => NormalizeHeaderFooterReferencesResult;
+//#endregion
+export { normalizeHeaderFooterReferences };

package/dist/docx/headerFooterReferenceNormalization.js

@@ -0,0 +1,64 @@
+//#region src/docx/headerFooterReferenceNormalization.ts
+const normalizeHeaderFooterReferences = ({ documentBody, headers, footers }) => {
+	const seenSectionProperties = /* @__PURE__ */ new Set();
+	let removedDanglingHeaderReferences = 0;
+	let removedDanglingFooterReferences = 0;
+	const normalizeSectionProperties = (sectionProperties) => {
+		if (!sectionProperties || seenSectionProperties.has(sectionProperties)) return;
+		seenSectionProperties.add(sectionProperties);
+		const headerResult = removeDanglingReferences(sectionProperties.headerReferences, headers);
+		if (headerResult.changed) {
+			removedDanglingHeaderReferences += headerResult.removed;
+			if (headerResult.references.length > 0) sectionProperties.headerReferences = headerResult.references;
+			else delete sectionProperties.headerReferences;
+		}
+		const footerResult = removeDanglingReferences(sectionProperties.footerReferences, footers);
+		if (footerResult.changed) {
+			removedDanglingFooterReferences += footerResult.removed;
+			if (footerResult.references.length > 0) sectionProperties.footerReferences = footerResult.references;
+			else delete sectionProperties.footerReferences;
+		}
+	};
+	const normalizeParagraph = (paragraph) => {
+		normalizeSectionProperties(paragraph.sectionProperties);
+	};
+	const normalizeTable = (table) => {
+		for (const row of table.rows) for (const cell of row.cells) normalizeBlocks(cell.content);
+	};
+	const normalizeBlock = (block) => {
+		if (block.type === "paragraph") {
+			normalizeParagraph(block);
+			return;
+		}
+		if (block.type === "table") {
+			normalizeTable(block);
+			return;
+		}
+		normalizeBlocks(block.content);
+	};
+	const normalizeBlocks = (blocks) => {
+		for (const block of blocks) normalizeBlock(block);
+	};
+	normalizeBlocks(documentBody.content);
+	normalizeSectionProperties(documentBody.finalSectionProperties);
+	for (const section of documentBody.sections ?? []) normalizeSectionProperties(section.properties);
+	return {
+		removedDanglingHeaderReferences,
+		removedDanglingFooterReferences
+	};
+};
+const removeDanglingReferences = (references, validParts) => {
+	if (!references || !validParts) return {
+		changed: false,
+		references: references ?? [],
+		removed: 0
+	};
+	const kept = references.filter((reference) => validParts.has(reference.rId));
+	return {
+		changed: kept.length !== references.length,
+		references: kept,
+		removed: references.length - kept.length
+	};
+};
+//#endregion
+export { normalizeHeaderFooterReferences };

package/dist/docx/hyperlinkParser.d.ts

@@ -0,0 +1,108 @@
+import { document_d_exports } from "../types/document.js";
+import { StyleMap } from "./styleParser.js";
+import { XmlElement } from "./xmlParser.js";
+
+//#region src/docx/hyperlinkParser.d.ts
+/**
+ * Parse a hyperlink element (w:hyperlink)
+ *
+ * Handles both external links (via r:id relationship) and internal
+ * links (via w:anchor bookmark reference).
+ *
+ * @param node - The w:hyperlink XML element
+ * @param rels - Relationship map to resolve r:id references
+ * @param styles - Style map for resolving run styles
+ * @param theme - Theme for resolving colors/fonts
+ * @param media - Media files map for image data
+ * @returns Parsed Hyperlink object
+ */
+declare function parseHyperlink(node: XmlElement, rels: document_d_exports.RelationshipMap | null, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, media?: Map<string, document_d_exports.MediaFile> | null, rootXmlns?: Record<string, string>): document_d_exports.Hyperlink;
+/**
+ * Get the display text of a hyperlink
+ *
+ * Concatenates text from all child runs.
+ *
+ * @param hyperlink - Parsed Hyperlink object
+ * @returns Display text string
+ */
+declare function getHyperlinkText(hyperlink: document_d_exports.Hyperlink): string;
+/**
+ * Check if a hyperlink is an external link
+ *
+ * @param hyperlink - Parsed Hyperlink object
+ * @returns true if this links to an external URL
+ */
+declare function isExternalLink(hyperlink: document_d_exports.Hyperlink): boolean;
+/**
+ * Check if a hyperlink is an internal bookmark link
+ *
+ * @param hyperlink - Parsed Hyperlink object
+ * @returns true if this links to an internal bookmark
+ */
+declare function isInternalLink(hyperlink: document_d_exports.Hyperlink): boolean;
+/**
+ * Get the resolved URL of a hyperlink
+ *
+ * For external links, returns the full URL.
+ * For internal links, returns the anchor prefixed with #.
+ * Returns undefined if the link couldn't be resolved.
+ *
+ * @param hyperlink - Parsed Hyperlink object
+ * @returns Resolved URL or undefined
+ */
+declare function getHyperlinkUrl(hyperlink: document_d_exports.Hyperlink): string | undefined;
+/**
+ * Check if a hyperlink has any content (runs)
+ *
+ * @param hyperlink - Parsed Hyperlink object
+ * @returns true if hyperlink has child runs
+ */
+declare function hasContent(hyperlink: document_d_exports.Hyperlink): boolean;
+/**
+ * Get all runs from a hyperlink
+ *
+ * @param hyperlink - Parsed Hyperlink object
+ * @returns Array of Run objects
+ */
+declare function getHyperlinkRuns(hyperlink: document_d_exports.Hyperlink): document_d_exports.Run[];
+/**
+ * Resolve a hyperlink's rId to a URL using a relationship map
+ *
+ * This is useful when you have a hyperlink that was parsed without
+ * relationship context and need to resolve it later.
+ *
+ * @param hyperlink - Parsed Hyperlink object (will be modified)
+ * @param rels - Relationship map to resolve against
+ * @returns The resolved URL or undefined
+ */
+declare function resolveHyperlinkUrl(hyperlink: document_d_exports.Hyperlink, rels: document_d_exports.RelationshipMap): string | undefined;
+/**
+ * Create an internal hyperlink to a bookmark
+ *
+ * Utility function for creating hyperlinks programmatically.
+ *
+ * @param anchor - Bookmark name to link to
+ * @param children - Child runs for display text
+ * @param options - Optional properties (tooltip, etc.)
+ * @returns New Hyperlink object
+ */
+declare function createInternalHyperlink(anchor: string, children: document_d_exports.Run[], options?: {
+  tooltip?: string;
+}): document_d_exports.Hyperlink;
+/**
+ * Create an external hyperlink
+ *
+ * Utility function for creating hyperlinks programmatically.
+ * Note: The rId would need to be assigned when serializing.
+ *
+ * @param url - External URL
+ * @param children - Child runs for display text
+ * @param options - Optional properties (tooltip, target, etc.)
+ * @returns New Hyperlink object
+ */
+declare function createExternalHyperlink(url: string, children: document_d_exports.Run[], options?: {
+  tooltip?: string;
+  target?: string;
+}): document_d_exports.Hyperlink;
+//#endregion
+export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, resolveHyperlinkUrl };

package/dist/docx/hyperlinkParser.js

@@ -0,0 +1,230 @@
+import { getAttribute, getChildElements, mergeXmlnsDeclarations, parseNumericAttribute } from "./xmlParser.js";
+import { parseRun } from "./runParser.js";
+import { sanitizeExternalUrl, sanitizeLinkTarget } from "../utils/urlSecurity.js";
+//#region src/docx/hyperlinkParser.ts
+/**
+* Get the local name of an element (without namespace prefix)
+*/
+function getLocalName(name) {
+	if (!name) return "";
+	const colonIndex = name.indexOf(":");
+	return colonIndex !== -1 ? name.slice(colonIndex + 1) : name;
+}
+/**
+* Parse bookmark start (w:bookmarkStart)
+*
+* Used for internal hyperlink targets within the document.
+*/
+function parseBookmarkStart(node) {
+	const bookmark = {
+		type: "bookmarkStart",
+		id: parseNumericAttribute(node, "w", "id") ?? 0,
+		name: getAttribute(node, "w", "name") ?? ""
+	};
+	const colFirst = parseNumericAttribute(node, "w", "colFirst");
+	if (colFirst !== void 0) bookmark.colFirst = colFirst;
+	const colLast = parseNumericAttribute(node, "w", "colLast");
+	if (colLast !== void 0) bookmark.colLast = colLast;
+	return bookmark;
+}
+/**
+* Parse bookmark end (w:bookmarkEnd)
+*/
+function parseBookmarkEnd(node) {
+	return {
+		type: "bookmarkEnd",
+		id: parseNumericAttribute(node, "w", "id") ?? 0
+	};
+}
+/**
+* Parse a hyperlink element (w:hyperlink)
+*
+* Handles both external links (via r:id relationship) and internal
+* links (via w:anchor bookmark reference).
+*
+* @param node - The w:hyperlink XML element
+* @param rels - Relationship map to resolve r:id references
+* @param styles - Style map for resolving run styles
+* @param theme - Theme for resolving colors/fonts
+* @param media - Media files map for image data
+* @returns Parsed Hyperlink object
+*/
+function parseHyperlink(node, rels, styles = null, theme = null, media = null, rootXmlns = {}) {
+	const hyperlink = {
+		type: "hyperlink",
+		children: []
+	};
+	const rId = getAttribute(node, "r", "id");
+	if (rId) {
+		hyperlink.rId = rId;
+		if (rels) {
+			const rel = rels.get(rId);
+			if (rel) {
+				const safeHref = sanitizeExternalUrl(rel.target);
+				if (safeHref) hyperlink.href = safeHref;
+			}
+		}
+	}
+	const anchor = getAttribute(node, "w", "anchor");
+	if (anchor) {
+		hyperlink.anchor = anchor;
+		if (!hyperlink.href) hyperlink.href = `#${anchor}`;
+	}
+	const tooltip = getAttribute(node, "w", "tooltip");
+	if (tooltip) hyperlink.tooltip = tooltip;
+	const tgtFrame = getAttribute(node, "w", "tgtFrame");
+	if (tgtFrame) hyperlink.target = sanitizeLinkTarget(tgtFrame);
+	const history = getAttribute(node, "w", "history");
+	if (history === "1" || history === "true") hyperlink.history = true;
+	const docLocation = getAttribute(node, "w", "docLocation");
+	if (docLocation) hyperlink.docLocation = docLocation;
+	const inScopeXmlns = mergeXmlnsDeclarations(rootXmlns, node);
+	const children = getChildElements(node);
+	for (const child of children) switch (getLocalName(child.name)) {
+		case "r":
+			hyperlink.children.push(parseRun(child, styles, theme, rels, media, inScopeXmlns));
+			break;
+		case "bookmarkStart":
+			hyperlink.children.push(parseBookmarkStart(child));
+			break;
+		case "bookmarkEnd":
+			hyperlink.children.push(parseBookmarkEnd(child));
+			break;
+		default: break;
+	}
+	return hyperlink;
+}
+/**
+* Get the display text of a hyperlink
+*
+* Concatenates text from all child runs.
+*
+* @param hyperlink - Parsed Hyperlink object
+* @returns Display text string
+*/
+function getHyperlinkText(hyperlink) {
+	let text = "";
+	for (const child of hyperlink.children) if (child.type === "run") {
+		for (const content of child.content) if (content.type === "text") text += content.text;
+		else if (content.type === "tab") text += "	";
+	}
+	return text;
+}
+/**
+* Check if a hyperlink is an external link
+*
+* @param hyperlink - Parsed Hyperlink object
+* @returns true if this links to an external URL
+*/
+function isExternalLink(hyperlink) {
+	if (hyperlink.href) return sanitizeExternalUrl(hyperlink.href) !== void 0;
+	return !!hyperlink.rId && !hyperlink.anchor;
+}
+/**
+* Check if a hyperlink is an internal bookmark link
+*
+* @param hyperlink - Parsed Hyperlink object
+* @returns true if this links to an internal bookmark
+*/
+function isInternalLink(hyperlink) {
+	return !!hyperlink.anchor;
+}
+/**
+* Get the resolved URL of a hyperlink
+*
+* For external links, returns the full URL.
+* For internal links, returns the anchor prefixed with #.
+* Returns undefined if the link couldn't be resolved.
+*
+* @param hyperlink - Parsed Hyperlink object
+* @returns Resolved URL or undefined
+*/
+function getHyperlinkUrl(hyperlink) {
+	return hyperlink.href;
+}
+/**
+* Check if a hyperlink has any content (runs)
+*
+* @param hyperlink - Parsed Hyperlink object
+* @returns true if hyperlink has child runs
+*/
+function hasContent(hyperlink) {
+	return hyperlink.children.some((child) => child.type === "run");
+}
+/**
+* Get all runs from a hyperlink
+*
+* @param hyperlink - Parsed Hyperlink object
+* @returns Array of Run objects
+*/
+function getHyperlinkRuns(hyperlink) {
+	return hyperlink.children.filter((child) => child.type === "run");
+}
+/**
+* Resolve a hyperlink's rId to a URL using a relationship map
+*
+* This is useful when you have a hyperlink that was parsed without
+* relationship context and need to resolve it later.
+*
+* @param hyperlink - Parsed Hyperlink object (will be modified)
+* @param rels - Relationship map to resolve against
+* @returns The resolved URL or undefined
+*/
+function resolveHyperlinkUrl(hyperlink, rels) {
+	if (hyperlink.rId) {
+		const rel = rels.get(hyperlink.rId);
+		if (rel) {
+			const safeHref = sanitizeExternalUrl(rel.target);
+			if (safeHref) {
+				hyperlink.href = safeHref;
+				return hyperlink.href;
+			}
+		}
+	}
+	if (hyperlink.anchor && !hyperlink.href) {
+		hyperlink.href = `#${hyperlink.anchor}`;
+		return hyperlink.href;
+	}
+	return hyperlink.href;
+}
+/**
+* Create an internal hyperlink to a bookmark
+*
+* Utility function for creating hyperlinks programmatically.
+*
+* @param anchor - Bookmark name to link to
+* @param children - Child runs for display text
+* @param options - Optional properties (tooltip, etc.)
+* @returns New Hyperlink object
+*/
+function createInternalHyperlink(anchor, children, options) {
+	return {
+		type: "hyperlink",
+		anchor,
+		href: `#${anchor}`,
+		...options?.tooltip !== void 0 ? { tooltip: options.tooltip } : {},
+		children
+	};
+}
+/**
+* Create an external hyperlink
+*
+* Utility function for creating hyperlinks programmatically.
+* Note: The rId would need to be assigned when serializing.
+*
+* @param url - External URL
+* @param children - Child runs for display text
+* @param options - Optional properties (tooltip, target, etc.)
+* @returns New Hyperlink object
+*/
+function createExternalHyperlink(url, children, options) {
+	return {
+		type: "hyperlink",
+		href: url,
+		...options?.tooltip !== void 0 ? { tooltip: options.tooltip } : {},
+		...options?.target !== void 0 ? { target: options.target } : {},
+		children
+	};
+}
+//#endregion
+export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, resolveHyperlinkUrl };

package/dist/docx/imageParser.d.ts

@@ -0,0 +1,93 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+
+//#region src/docx/imageParser.d.ts
+/**
+ * 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
+ */
+declare function resolveImageData(rId: string, rels: document_d_exports.RelationshipMap | undefined, media: Map<string, document_d_exports.MediaFile> | undefined): {
+  src?: string;
+  mimeType?: string;
+  filename?: string;
+};
+/**
+ * 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
+ */
+declare function parseDrawing(drawingEl: XmlElement, rels: document_d_exports.RelationshipMap | undefined, media: Map<string, document_d_exports.MediaFile> | undefined): document_d_exports.Image | 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
+ */
+declare function parseImage(node: XmlElement, rels: document_d_exports.RelationshipMap | undefined, media: Map<string, document_d_exports.MediaFile> | undefined): document_d_exports.Image | null;
+/**
+ * Check if an image is inline (not floating)
+ */
+declare function isInlineImage(image: document_d_exports.Image): boolean;
+/**
+ * Check if an image is floating (anchored)
+ */
+declare function isFloatingImage(image: document_d_exports.Image): boolean;
+/**
+ * Check if an image is behind text
+ */
+declare function isBehindText(image: document_d_exports.Image): boolean;
+/**
+ * Check if an image is in front of text
+ */
+declare function isInFrontOfText(image: document_d_exports.Image): boolean;
+/**
+ * Get image width in pixels
+ */
+declare function getImageWidthPx(image: document_d_exports.Image): number;
+/**
+ * Get image height in pixels
+ */
+declare function getImageHeightPx(image: document_d_exports.Image): number;
+/**
+ * Get image dimensions in pixels
+ */
+declare function getImageDimensionsPx(image: document_d_exports.Image): {
+  width: number;
+  height: number;
+};
+/**
+ * Check if image has alt text (for accessibility)
+ */
+declare function hasAltText(image: document_d_exports.Image): boolean;
+/**
+ * Check if image is decorative (should be ignored by screen readers)
+ */
+declare function isDecorativeImage(image: document_d_exports.Image): boolean;
+/**
+ * Get wrap distances in pixels
+ */
+declare function getWrapDistancesPx(image: document_d_exports.Image): {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+};
+/**
+ * Check if image needs text wrapping
+ */
+declare function needsTextWrapping(image: document_d_exports.Image): boolean;
+//#endregion
+export { getImageDimensionsPx, getImageHeightPx, getImageWidthPx, getWrapDistancesPx, hasAltText, isBehindText, isDecorativeImage, isFloatingImage, isInFrontOfText, isInlineImage, needsTextWrapping, parseDrawing, parseImage, resolveImageData };