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

package/dist/docx/blockContentParser.js

@@ -0,0 +1,289 @@
+import { elementToXml, findChild, findDeep, getChildElements, getLocalName, mergeXmlnsDeclarations } from "./xmlParser.js";
+import { parseBookmarkEnd, parseBookmarkStart } from "./bookmarkParser.js";
+import { getTextBoxContentElement, isTextBoxDrawing, parseTextBox, parseTextBoxContent } from "./textBoxParser.js";
+import { parseSdtProperties } from "./sdtProperties.js";
+import { parseParagraph } from "./paragraphParser.js";
+import { appendBookmarkMarkerToLastParagraphInBlocks, prependBookmarkMarkersToFirstParagraphInBlocks } from "./bookmarkPlacement.js";
+import { parseTable } from "./tableParser.js";
+import { padDecimal } from "./numberingParser.js";
+import { convertBulletToUnicode } from "./bulletMarkers.js";
+//#region src/docx/blockContentParser.ts
+const toRoman = (numParam) => {
+	let num = numParam;
+	const romanNumerals = [
+		[1e3, "M"],
+		[900, "CM"],
+		[500, "D"],
+		[400, "CD"],
+		[100, "C"],
+		[90, "XC"],
+		[50, "L"],
+		[40, "XL"],
+		[10, "X"],
+		[9, "IX"],
+		[5, "V"],
+		[4, "IV"],
+		[1, "I"]
+	];
+	let result = "";
+	for (const [value, symbol] of romanNumerals) while (num >= value) {
+		result += symbol;
+		num -= value;
+	}
+	return result;
+};
+const toRepeatedLetter = (value, baseCodePoint) => {
+	if (value <= 0) return "0";
+	const zeroBased = value - 1;
+	return String.fromCodePoint(baseCodePoint + zeroBased % 26).repeat(Math.floor(zeroBased / 26) + 1);
+};
+const formatNumber = (value, numFmt) => {
+	switch (numFmt) {
+		case "decimal": return String(value);
+		case "decimalZero": return padDecimal(value, 2);
+		case "decimalZero3": return padDecimal(value, 3);
+		case "decimalZero4": return padDecimal(value, 4);
+		case "decimalZero5": return padDecimal(value, 5);
+		case "lowerLetter": return toRepeatedLetter(value, 97);
+		case "upperLetter": return toRepeatedLetter(value, 65);
+		case "lowerRoman": return toRoman(value).toLowerCase();
+		case "upperRoman": return toRoman(value);
+		case "bullet": return "•";
+		default: return String(value);
+	}
+};
+const computeListMarker = (paragraph, numbering, listCounters, abstractCounters) => {
+	const listRendering = paragraph.listRendering;
+	if (!listRendering || !numbering) return;
+	const { numId, level } = listRendering;
+	if (numId === 0) return;
+	if (!listCounters.has(numId)) listCounters.set(numId, Array.from({ length: 9 }).fill(0));
+	const counters = listCounters.get(numId);
+	if (!counters) return;
+	const abstractNumId = numbering.getAbstractNumId(numId);
+	if (abstractNumId !== null && level > 0) {
+		const latestAbstractCounters = abstractCounters.get(abstractNumId);
+		const missingParentCounters = counters.slice(0, level).every((value) => value === 0);
+		if (latestAbstractCounters && missingParentCounters) for (let i = 0; i < level; i += 1) counters[i] = latestAbstractCounters[i] ?? 0;
+	}
+	counters[level] = (counters[level] || 0) + 1;
+	for (let i = level + 1; i < counters.length; i += 1) counters[i] = 0;
+	const childAdvances = listRendering.implicitChildLevelAdvances ?? 0;
+	if (childAdvances > 0 && level + 1 < counters.length) counters[level + 1] = (counters[level + 1] ?? 0) + childAdvances;
+	if (abstractNumId !== null) abstractCounters.set(abstractNumId, [...counters]);
+	const pattern = listRendering.marker;
+	if (listRendering.isBullet) {
+		listRendering.marker = convertBulletToUnicode(pattern || "");
+		return;
+	}
+	let computedMarker = pattern;
+	const useLegalNumbering = numbering.getLevel(numId, level)?.isLgl === true || listRendering.isLegal === true;
+	for (let lvl = 0; lvl <= level; lvl += 1) {
+		const placeholder = `%${lvl + 1}`;
+		if (computedMarker.includes(placeholder)) {
+			const value = counters[lvl] ?? 0;
+			const levelInfo = numbering.getLevel(numId, lvl);
+			const formatted = formatNumber(value, useLegalNumbering ? "decimal" : levelInfo?.numFmt || "decimal");
+			computedMarker = computedMarker.replaceAll(placeholder, formatted);
+		}
+	}
+	listRendering.marker = computedMarker;
+};
+const enrichParagraphTextBoxes = (paragraph, paraXml, styles, theme, numbering, rels, media) => {
+	if (paragraph.content.length === 0) return;
+	const xmlChildren = getChildElements(paraXml);
+	let parsedIndex = 0;
+	let lastConsumedRun;
+	for (const xmlChild of xmlChildren) {
+		if (getLocalName(xmlChild.name ?? "") !== "r") {
+			if (parsedIndex < paragraph.content.length && paragraph.content[parsedIndex]?.type !== "run") parsedIndex += 1;
+			continue;
+		}
+		const { textBoxDrawings, hasNonTextBoxContent } = scanRunForTextBoxDrawings(xmlChild);
+		const parsedContent = paragraph.content[parsedIndex];
+		const parsedRun = parsedContent?.type === "run" ? parsedContent : void 0;
+		const targetRun = parsedRun ?? (hasNonTextBoxContent ? lastConsumedRun : void 0);
+		for (const runEl of textBoxDrawings) {
+			const textBox = parseTextBox(runEl);
+			if (!textBox) continue;
+			const wsp = findDeep(runEl, "wps", "wsp");
+			if (wsp) {
+				const txbxContentEl = getTextBoxContentElement(wsp);
+				if (txbxContentEl) textBox.content = parseTextBoxContent(txbxContentEl, parseParagraph, null, styles, theme, numbering, rels ?? void 0, media ?? void 0);
+			}
+			const shape = {
+				type: "shape",
+				shapeType: "textBox",
+				size: textBox.size,
+				...textBox.position !== void 0 ? { position: textBox.position } : {},
+				...textBox.wrap !== void 0 ? { wrap: textBox.wrap } : {},
+				...textBox.fill !== void 0 ? { fill: textBox.fill } : {},
+				...textBox.outline !== void 0 ? { outline: textBox.outline } : {},
+				textBody: {
+					content: textBox.content,
+					...textBox.margins !== void 0 ? { margins: textBox.margins } : {}
+				}
+			};
+			if (textBox.id) shape.id = textBox.id;
+			const shapeContent = {
+				type: "shape",
+				shape
+			};
+			if (targetRun && hasNonTextBoxContent) targetRun.content.push(shapeContent);
+			else {
+				const newRun = {
+					type: "run",
+					content: [shapeContent]
+				};
+				paragraph.content.splice(parsedIndex, 0, newRun);
+				lastConsumedRun = newRun;
+				parsedIndex += 1;
+			}
+		}
+		if (hasNonTextBoxContent && parsedRun) {
+			lastConsumedRun = parsedRun;
+			parsedIndex += 1;
+		}
+	}
+};
+const scanRunForTextBoxDrawings = (xmlRun) => {
+	const textBoxDrawings = [];
+	let hasNonTextBoxContent = false;
+	const visitDrawing = (drawingEl) => {
+		if (isTextBoxDrawing(drawingEl)) {
+			textBoxDrawings.push(drawingEl);
+			return;
+		}
+		hasNonTextBoxContent = true;
+	};
+	for (const el of getChildElements(xmlRun)) {
+		const name = getLocalName(el.name ?? "");
+		if (name === "rPr") continue;
+		if (name === "drawing") {
+			visitDrawing(el);
+			continue;
+		}
+		if (name === "AlternateContent") {
+			const branches = getChildElements(el);
+			const choice = branches.find((branch) => getLocalName(branch.name ?? "") === "Choice");
+			const fallback = branches.find((branch) => getLocalName(branch.name ?? "") === "Fallback");
+			const tryBranch = (branch) => {
+				if (!branch) return false;
+				let found = false;
+				for (const innerEl of getChildElements(branch)) if (getLocalName(innerEl.name ?? "") === "drawing") {
+					visitDrawing(innerEl);
+					found = true;
+				}
+				return found;
+			};
+			let foundInBranch = tryBranch(choice);
+			if (!foundInBranch) foundInBranch = tryBranch(fallback);
+			if (!foundInBranch) hasNonTextBoxContent = true;
+			continue;
+		}
+		hasNonTextBoxContent = true;
+	}
+	return {
+		textBoxDrawings,
+		hasNonTextBoxContent
+	};
+};
+const parseBlockContent = (parent, styles, theme, numbering, rels, media, options) => parseBlockContentWithState(parent, styles, theme, numbering, rels, media, {
+	listCounters: /* @__PURE__ */ new Map(),
+	abstractCounters: /* @__PURE__ */ new Map(),
+	options: {
+		...options,
+		rootXmlns: mergeXmlnsDeclarations(options?.rootXmlns ?? {}, parent)
+	}
+});
+const parseBlockContentWithState = (parent, styles, theme, numbering, rels, media, state) => {
+	const content = [];
+	const children = getChildElements(parent);
+	const pendingBookmarkMarkers = [];
+	for (const child of children) {
+		const localName = getLocalName(child.name ?? "");
+		if (localName === "p") {
+			const paragraph = parseParagraph(child, styles, theme, numbering, rels, media, state.options);
+			prependPendingBookmarkMarkers(paragraph, pendingBookmarkMarkers);
+			enrichParagraphTextBoxes(paragraph, child, styles, theme, numbering, rels, media);
+			computeListMarker(paragraph, numbering, state.listCounters, state.abstractCounters);
+			content.push(paragraph);
+			continue;
+		}
+		if (localName === "tbl") {
+			const table = parseTable(child, styles, theme, numbering, rels, media, state.options);
+			if (prependBookmarkMarkersToFirstParagraphInBlocks([table], pendingBookmarkMarkers)) pendingBookmarkMarkers.length = 0;
+			content.push(table);
+			continue;
+		}
+		if (localName === "sdt") {
+			const sdtPr = findChild(child, "w", "sdtPr");
+			const sdtEndPr = findChild(child, "w", "sdtEndPr");
+			const sdtContent = findChild(child, "w", "sdtContent");
+			const properties = parseSdtProperties(sdtPr, sdtEndPr);
+			const captured = captureSdtSiblingMarkers(child);
+			if (captured.before.length > 0) properties.rawSdtChildrenBeforeContent = captured.before;
+			if (captured.after.length > 0) properties.rawSdtChildrenAfterContent = captured.after;
+			const blockSdt = {
+				type: "blockSdt",
+				properties,
+				content: sdtContent ? parseBlockContentWithState(sdtContent, styles, theme, numbering, rels, media, state) : []
+			};
+			if (prependBookmarkMarkersToFirstParagraphInBlocks(blockSdt.content, pendingBookmarkMarkers)) pendingBookmarkMarkers.length = 0;
+			content.push(blockSdt);
+			continue;
+		}
+		if (localName === "bookmarkStart" || localName === "bookmarkEnd") {
+			const marker = parseBookmarkMarker(child, localName);
+			if (!appendBookmarkMarkerToLastParagraphInBlocks(content, marker)) pendingBookmarkMarkers.push(marker);
+		}
+	}
+	if (pendingBookmarkMarkers.length > 0) content.push({
+		type: "paragraph",
+		content: [...pendingBookmarkMarkers]
+	});
+	return content;
+};
+/**
+* Walk a `<w:sdt>` element's direct children and return the verbatim XML
+* for every child that is NOT `<w:sdtPr>`, `<w:sdtEndPr>`, or
+* `<w:sdtContent>` — split by position relative to sdtContent.
+*
+* Per MS-OE376 §2.5.2.30, Word emits 16 range-marker elements (bookmark,
+* comment, custom XML, tracked-change ranges) as direct sdt siblings of
+* sdtContent. Without preserving them, a comment thread or tracked
+* change that crosses an SDT boundary loses a delimiter when folio
+* serializes the parsed model back out.
+*/
+const captureSdtSiblingMarkers = (sdt) => {
+	const beforeParts = [];
+	const afterParts = [];
+	let sawContent = false;
+	for (const ch of sdt.elements ?? []) {
+		if (ch.type !== "element" || !ch.name) continue;
+		const local = getLocalName(ch.name);
+		if (local === "sdtPr" || local === "sdtEndPr") continue;
+		if (local === "sdtContent") {
+			sawContent = true;
+			continue;
+		}
+		const xml = elementToXml(ch);
+		if (sawContent) afterParts.push(xml);
+		else beforeParts.push(xml);
+	}
+	return {
+		before: beforeParts.join(""),
+		after: afterParts.join("")
+	};
+};
+const parseBookmarkMarker = (child, localName) => {
+	if (localName === "bookmarkStart") return parseBookmarkStart(child);
+	return parseBookmarkEnd(child);
+};
+const prependPendingBookmarkMarkers = (paragraph, pendingBookmarkMarkers) => {
+	if (pendingBookmarkMarkers.length === 0) return;
+	paragraph.content.unshift(...pendingBookmarkMarkers);
+	pendingBookmarkMarkers.length = 0;
+};
+//#endregion
+export { parseBlockContent };

package/dist/docx/bookmarkParser.d.ts

@@ -0,0 +1,178 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+
+//#region src/docx/bookmarkParser.d.ts
+/**
+ * Parse a bookmark start element (w:bookmarkStart)
+ *
+ * Extracts:
+ * - id: Numeric identifier (required, matches with bookmarkEnd)
+ * - name: Bookmark name (required, used by hyperlinks)
+ * - colFirst: First column for table bookmarks (optional)
+ * - colLast: Last column for table bookmarks (optional)
+ *
+ * @param node - The w:bookmarkStart XML element
+ * @returns Parsed BookmarkStart object
+ */
+declare function parseBookmarkStart(node: XmlElement): document_d_exports.BookmarkStart;
+/**
+ * Parse a bookmark end element (w:bookmarkEnd)
+ *
+ * Bookmark ends only contain an ID that matches the corresponding start marker.
+ *
+ * @param node - The w:bookmarkEnd XML element
+ * @returns Parsed BookmarkEnd object
+ */
+declare function parseBookmarkEnd(node: XmlElement): document_d_exports.BookmarkEnd;
+/**
+ * Bookmark map for quick lookup by ID or name
+ */
+type BookmarkMap = {
+  /** Lookup bookmark start by ID */byId: Map<number, document_d_exports.BookmarkStart>; /** Lookup bookmark start by name (for hyperlink resolution) */
+  byName: Map<string, document_d_exports.BookmarkStart>; /** All bookmark starts in document order */
+  bookmarks: document_d_exports.BookmarkStart[];
+};
+/**
+ * Create an empty bookmark map
+ */
+declare function createBookmarkMap(): BookmarkMap;
+/**
+ * Add a bookmark to the map
+ *
+ * @param map - The bookmark map to update
+ * @param bookmark - The bookmark start to add
+ */
+declare function addBookmark(map: BookmarkMap, bookmark: document_d_exports.BookmarkStart): void;
+/**
+ * Get a bookmark by name (for resolving internal hyperlinks)
+ *
+ * @param map - The bookmark map to search
+ * @param name - Bookmark name to find
+ * @returns The BookmarkStart or undefined if not found
+ */
+declare function getBookmarkByName(map: BookmarkMap, name: string): document_d_exports.BookmarkStart | undefined;
+/**
+ * Get a bookmark by ID (for matching start/end pairs)
+ *
+ * @param map - The bookmark map to search
+ * @param id - Bookmark ID to find
+ * @returns The BookmarkStart or undefined if not found
+ */
+declare function getBookmarkById(map: BookmarkMap, id: number): document_d_exports.BookmarkStart | undefined;
+/**
+ * Check if a bookmark exists by name
+ *
+ * @param map - The bookmark map to search
+ * @param name - Bookmark name to check
+ * @returns true if bookmark exists
+ */
+declare function hasBookmark(map: BookmarkMap, name: string): boolean;
+/**
+ * Get all bookmark names in the document
+ *
+ * @param map - The bookmark map
+ * @returns Array of bookmark names
+ */
+declare function getAllBookmarkNames(map: BookmarkMap): string[];
+/**
+ * Check if a bookmark is a point bookmark (start and end at same location)
+ *
+ * Point bookmarks have no content between start and end markers.
+ * This is commonly used for insertion points.
+ *
+ * @param start - The bookmark start
+ * @param end - The bookmark end
+ * @param contents - Content between them
+ * @returns true if this is a point bookmark
+ */
+declare function isPointBookmark(start: document_d_exports.BookmarkStart, end: document_d_exports.BookmarkEnd, contents: unknown[]): boolean;
+/**
+ * Check if a bookmark is a table column bookmark
+ *
+ * Table bookmarks have colFirst and colLast attributes indicating
+ * they span specific table columns.
+ *
+ * @param bookmark - The bookmark to check
+ * @returns true if bookmark has column range info
+ */
+declare function isTableBookmark(bookmark: document_d_exports.BookmarkStart): boolean;
+/**
+ * Generate an internal hyperlink href from a bookmark name
+ *
+ * Internal hyperlinks use #anchor format.
+ *
+ * @param bookmarkName - The bookmark name to link to
+ * @returns Href string (e.g., "#BookmarkName")
+ */
+declare function bookmarkToHref(bookmarkName: string): string;
+/**
+ * Extract bookmark name from an internal hyperlink href
+ *
+ * @param href - The href string
+ * @returns Bookmark name or null if not an internal link
+ */
+declare function hrefToBookmarkName(href: string): string | null;
+/**
+ * Check if a bookmark is a built-in Word bookmark
+ *
+ * Word uses certain reserved bookmark names for special purposes:
+ * - _GoBack: Last editing position
+ * - _Toc*: Table of contents entries
+ * - _Ref*: Cross-reference anchors
+ * - _Hlt*: Highlight ranges
+ *
+ * @param name - Bookmark name to check
+ * @returns true if this is a built-in bookmark
+ */
+declare function isBuiltInBookmark(name: string): boolean;
+/**
+ * Check if a bookmark is a TOC entry bookmark
+ *
+ * @param name - Bookmark name to check
+ * @returns true if bookmark is for TOC
+ */
+declare function isTocBookmark(name: string): boolean;
+/**
+ * Check if a bookmark is a cross-reference anchor
+ *
+ * @param name - Bookmark name to check
+ * @returns true if bookmark is for cross-reference
+ */
+declare function isRefBookmark(name: string): boolean;
+/**
+ * Get bookmark type category
+ *
+ * @param name - Bookmark name
+ * @returns Bookmark type
+ */
+declare function getBookmarkType(name: string): "user" | "toc" | "ref" | "goBack" | "internal";
+/**
+ * Validate that all bookmark starts have matching ends
+ *
+ * @param starts - Array of bookmark starts
+ * @param ends - Array of bookmark ends
+ * @returns Object with validation results
+ */
+declare function validateBookmarkPairs(starts: document_d_exports.BookmarkStart[], ends: document_d_exports.BookmarkEnd[]): {
+  valid: boolean;
+  unmatchedStarts: document_d_exports.BookmarkStart[];
+  unmatchedEnds: document_d_exports.BookmarkEnd[];
+};
+/**
+ * Validate a bookmark name (for creating new bookmarks)
+ *
+ * Valid bookmark names:
+ * - Cannot be empty
+ * - Must start with a letter or underscore
+ * - Can contain letters, digits, and underscores
+ * - Cannot exceed 40 characters
+ *
+ * @param name - Name to validate
+ * @returns Object with validation result and error message if invalid
+ */
+declare function validateBookmarkName(name: string): {
+  valid: boolean;
+  error?: string;
+};
+//#endregion
+export { BookmarkMap, addBookmark, bookmarkToHref, createBookmarkMap, getAllBookmarkNames, getBookmarkById, getBookmarkByName, getBookmarkType, hasBookmark, hrefToBookmarkName, isBuiltInBookmark, isPointBookmark, isRefBookmark, isTableBookmark, isTocBookmark, parseBookmarkEnd, parseBookmarkStart, validateBookmarkName, validateBookmarkPairs };