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

package/dist/docx/commentReplyMarkers.js

@@ -0,0 +1,123 @@
+//#region src/docx/commentReplyMarkers.ts
+const surfacesFromDocument = (doc) => ({
+	body: doc.package.document.content,
+	comments: doc.package.document.comments ?? [],
+	...doc.package.headers !== void 0 ? { headers: doc.package.headers } : {},
+	...doc.package.footers !== void 0 ? { footers: doc.package.footers } : {},
+	...doc.package.footnotes !== void 0 ? { footnotes: doc.package.footnotes } : {},
+	...doc.package.endnotes !== void 0 ? { endnotes: doc.package.endnotes } : {}
+});
+const surfaceBlockGroups = (surfaces) => {
+	const groups = [surfaces.body ?? []];
+	for (const header of surfaces.headers?.values() ?? []) groups.push(header.content ?? []);
+	for (const footer of surfaces.footers?.values() ?? []) groups.push(footer.content ?? []);
+	for (const footnote of surfaces.footnotes ?? []) groups.push(footnote.content ?? []);
+	for (const endnote of surfaces.endnotes ?? []) groups.push(endnote.content ?? []);
+	return groups;
+};
+const eachParagraph = (blocks, visit) => {
+	for (const block of blocks ?? []) {
+		if (block.type === "paragraph") {
+			visit(block);
+			continue;
+		}
+		if (block.type === "table") {
+			for (const row of block.rows ?? []) for (const cell of row.cells ?? []) eachParagraph(cell.content ?? [], visit);
+			continue;
+		}
+		eachParagraph(block.content ?? [], visit);
+	}
+};
+const scanAnchors = (surfaces) => {
+	const rangeIds = /* @__PURE__ */ new Set();
+	const anchoredIds = /* @__PURE__ */ new Set();
+	for (const group of surfaceBlockGroups(surfaces)) eachParagraph(group, (paragraph) => {
+		for (const item of paragraph.content ?? []) if (item.type === "commentRangeStart") {
+			rangeIds.add(item.id);
+			anchoredIds.add(item.id);
+		} else if (item.type === "commentReference") anchoredIds.add(item.id);
+	});
+	return {
+		rangeIds,
+		anchoredIds
+	};
+};
+/** Replies whose parent is another comment (the threaded-discussion shape). */
+const commentParentedReplies = (comments) => {
+	const commentIds = new Set(comments.map((comment) => comment.id));
+	return comments.filter((comment) => comment.parentId !== void 0 && commentIds.has(comment.parentId));
+};
+const injectIntoParagraph = (paragraph, replyIdsByParent, parentsWithRange) => {
+	const content = paragraph.content ?? [];
+	if (!content.some((item) => {
+		if (item.type === "commentRangeStart" || item.type === "commentRangeEnd") return replyIdsByParent.has(item.id);
+		return item.type === "commentReference" && !parentsWithRange.has(item.id) ? replyIdsByParent.has(item.id) : false;
+	})) return 0;
+	const next = [];
+	let injected = 0;
+	for (const item of content) {
+		next.push(item);
+		if (item.type === "commentRangeStart") for (const replyId of replyIdsByParent.get(item.id) ?? []) {
+			next.push({
+				type: "commentRangeStart",
+				id: replyId
+			});
+			injected += 1;
+		}
+		else if (item.type === "commentRangeEnd") for (const replyId of replyIdsByParent.get(item.id) ?? []) next.push({
+			type: "commentRangeEnd",
+			id: replyId
+		});
+		else if (item.type === "commentReference" && !parentsWithRange.has(item.id)) for (const replyId of replyIdsByParent.get(item.id) ?? []) {
+			next.push({
+				type: "commentReference",
+				id: replyId
+			});
+			injected += 1;
+		}
+	}
+	paragraph.content = next;
+	return injected;
+};
+const synthesizeReplyRangeMarkers = (surfaces) => {
+	const replies = commentParentedReplies(surfaces.comments);
+	if (replies.length === 0) return 0;
+	const { rangeIds, anchoredIds } = scanAnchors(surfaces);
+	const replyIdsByParent = /* @__PURE__ */ new Map();
+	for (const reply of replies) {
+		if (anchoredIds.has(reply.id) || reply.parentId === void 0) continue;
+		const siblings = replyIdsByParent.get(reply.parentId) ?? [];
+		siblings.push(reply.id);
+		replyIdsByParent.set(reply.parentId, siblings);
+	}
+	if (replyIdsByParent.size === 0) return 0;
+	let injected = 0;
+	const visit = (paragraph) => {
+		injected += injectIntoParagraph(paragraph, replyIdsByParent, rangeIds);
+	};
+	for (const group of surfaceBlockGroups(surfaces)) eachParagraph(group, visit);
+	return injected;
+};
+/**
+* Synthesize reply range markers into a document model in place, so every
+* reply comment picks up its parent's anchor before `document.xml` is
+* serialized. Idempotent and safe to call on both save paths. Returns the
+* number of markers injected.
+*/
+const applyReplyThreadMarkers = (doc) => synthesizeReplyRangeMarkers(surfacesFromDocument(doc));
+/**
+* Whether the model holds a reply comment that has no anchor of its own yet —
+* i.e. one that still needs {@link applyReplyThreadMarkers} to run. The
+* selective-save path uses this to bail to a full repack, which is the path
+* that owns marker synthesis (selective only patches individually-changed
+* paragraphs, so it cannot add a reply's markers to the parent's paragraph).
+*/
+const hasUnsynthesizedReplyRanges = (doc) => {
+	const surfaces = surfacesFromDocument(doc);
+	const replies = commentParentedReplies(surfaces.comments);
+	if (replies.length === 0) return false;
+	const { anchoredIds } = scanAnchors(surfaces);
+	return replies.some((reply) => !anchoredIds.has(reply.id));
+};
+//#endregion
+export { applyReplyThreadMarkers, hasUnsynthesizedReplyRanges };

package/dist/docx/compatibility.d.ts

@@ -0,0 +1,12 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/docx/compatibility.d.ts
+type DocxCompatibilityReason = "opaqueDrawing";
+type DocxCompatibility = {
+  canSafelyEdit: boolean;
+  reasons: DocxCompatibilityReason[];
+  unsupportedContentCount: number;
+};
+declare function inspectDocxCompatibility(doc: document_d_exports.Document): DocxCompatibility;
+//#endregion
+export { DocxCompatibility, DocxCompatibilityReason, inspectDocxCompatibility };

package/dist/docx/compatibility.js

@@ -0,0 +1,77 @@
+//#region src/docx/compatibility.ts
+const COMPATIBLE_DOCX = {
+	canSafelyEdit: true,
+	reasons: [],
+	unsupportedContentCount: 0
+};
+function inspectDocxCompatibility(doc) {
+	const reasons = /* @__PURE__ */ new Set();
+	let unsupportedContentCount = 0;
+	const record = (reason) => {
+		reasons.add(reason);
+		unsupportedContentCount += 1;
+	};
+	inspectBlocks(doc.package.document.content, record);
+	for (const header of doc.package.headers?.values() ?? []) inspectHeaderFooter(header, record);
+	for (const footer of doc.package.footers?.values() ?? []) inspectHeaderFooter(footer, record);
+	for (const footnote of doc.package.footnotes ?? []) inspectBlocks(footnote.content, record);
+	for (const endnote of doc.package.endnotes ?? []) inspectBlocks(endnote.content, record);
+	if (unsupportedContentCount === 0) return COMPATIBLE_DOCX;
+	return {
+		canSafelyEdit: false,
+		reasons: Array.from(reasons),
+		unsupportedContentCount
+	};
+}
+function inspectBlocks(blocks, record) {
+	for (const block of blocks) {
+		if (block.type === "paragraph") {
+			inspectParagraphContent(block.content, record);
+			continue;
+		}
+		if (block.type === "table") {
+			for (const row of block.rows) for (const cell of row.cells) inspectBlocks(cell.content, record);
+			continue;
+		}
+		inspectBlocks(block.content, record);
+	}
+}
+function inspectHeaderFooter(headerFooter, record) {
+	inspectBlocks(headerFooter.content, record);
+}
+function inspectParagraphContent(content, record) {
+	for (const item of content) {
+		if (item.type === "run") {
+			inspectRun(item, record);
+			continue;
+		}
+		if (item.type === "hyperlink") {
+			inspectHyperlink(item, record);
+			continue;
+		}
+		if (item.type === "inlineSdt") {
+			inspectParagraphContent(item.content, record);
+			continue;
+		}
+		if (item.type === "insertion" || item.type === "deletion" || item.type === "moveFrom" || item.type === "moveTo") {
+			inspectParagraphContent(item.content, record);
+			continue;
+		}
+		if (item.type === "simpleField") {
+			inspectParagraphContent(item.content, record);
+			continue;
+		}
+		if (item.type === "complexField") {
+			for (const run of item.fieldCode) inspectRun(run, record);
+			for (const run of item.fieldResult) inspectRun(run, record);
+		}
+	}
+}
+function inspectHyperlink(hyperlink, record) {
+	for (const child of hyperlink.children) if (child.type === "run") inspectRun(child, record);
+}
+function inspectRun(run, record) {
+	for (const content of run.content) if (content.type === "drawing" && content.rawXml) record("opaqueDrawing");
+}
+//#endregion
+export { inspectDocxCompatibility };

package/dist/docx/documentParser.d.ts

@@ -0,0 +1,65 @@
+import { document_d_exports } from "../types/document.js";
+import { NumberingMap } from "./numberingParser.js";
+import { StyleMap } from "./styleParser.js";
+
+//#region src/docx/documentParser.d.ts
+/**
+ * Extract template variables from text
+ *
+ * @param text - Text to search for variables
+ * @returns Array of unique variable names (without braces)
+ */
+declare function extractTemplateVariables(text: string): string[];
+/**
+ * Extract all template variables from document content
+ *
+ * @param content - Array of paragraphs and tables
+ * @returns Array of unique variable names
+ */
+declare function extractAllTemplateVariables(content: document_d_exports.BlockContent[]): string[];
+/**
+ * Parse document.xml body content
+ *
+ * @param xml - Raw XML content of document.xml
+ * @param styles - Parsed style map
+ * @param theme - Parsed theme
+ * @param numbering - Parsed numbering definitions
+ * @param rels - Document relationships
+ * @param media - Media files
+ * @returns DocumentBody with content, sections, and template variables
+ */
+declare function parseDocumentBody(xml: string, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, numbering?: NumberingMap | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null): document_d_exports.DocumentBody;
+/**
+ * Get all paragraphs from document body (flattened)
+ */
+declare function getAllParagraphs(body: document_d_exports.DocumentBody): document_d_exports.Paragraph[];
+/**
+ * Get all tables from document body
+ */
+declare function getAllTables(body: document_d_exports.DocumentBody): document_d_exports.Table[];
+/**
+ * Get plain text from entire document body
+ */
+declare function getDocumentText(body: document_d_exports.DocumentBody): string;
+/**
+ * Count total paragraphs in document
+ */
+declare function getParagraphCount(body: document_d_exports.DocumentBody): number;
+/**
+ * Count total words in document (approximate)
+ */
+declare function getWordCount(body: document_d_exports.DocumentBody): number;
+/**
+ * Count total characters in document
+ */
+declare function getCharacterCount(body: document_d_exports.DocumentBody): number;
+/**
+ * Get section count
+ */
+declare function getSectionCount(body: document_d_exports.DocumentBody): number;
+/**
+ * Check if document has template variables
+ */
+declare function hasTemplateVariables(body: document_d_exports.DocumentBody): boolean;
+//#endregion
+export { extractAllTemplateVariables, extractTemplateVariables, getAllParagraphs, getAllTables, getCharacterCount, getDocumentText, getParagraphCount, getSectionCount, getWordCount, hasTemplateVariables, parseDocumentBody };

package/dist/docx/documentParser.js

@@ -0,0 +1,209 @@
+import { collectXmlnsDeclarations, findChild, parseXml } from "./xmlParser.js";
+import { getDefaultSectionProperties, parseSectionProperties } from "./sectionParser.js";
+import { getParagraphText } from "./paragraphParser.js";
+import { parseBlockContent } from "./blockContentParser.js";
+//#region src/docx/documentParser.ts
+/**
+* Regular expression to match template variables {{...}}
+*/
+const TEMPLATE_VARIABLE_REGEX = /\{(?<name>[a-zA-Z_][a-zA-Z0-9_\-.]*)\}/gu;
+/**
+* Extract template variables from text
+*
+* @param text - Text to search for variables
+* @returns Array of unique variable names (without braces)
+*/
+function extractTemplateVariables(text) {
+	const variables = [];
+	let match;
+	TEMPLATE_VARIABLE_REGEX.lastIndex = 0;
+	while ((match = TEMPLATE_VARIABLE_REGEX.exec(text)) !== null) {
+		const varName = match.groups["name"].trim();
+		if (varName && !variables.includes(varName)) variables.push(varName);
+	}
+	return variables;
+}
+/**
+* Extract all template variables from document content
+*
+* @param content - Array of paragraphs and tables
+* @returns Array of unique variable names
+*/
+function extractAllTemplateVariables(content) {
+	const variables = [];
+	for (const block of content) if (block.type === "paragraph") {
+		const vars = extractTemplateVariables(getParagraphText(block));
+		for (const v of vars) if (!variables.includes(v)) variables.push(v);
+	} else if (block.type === "table") {
+		const tableVars = extractTableVariables(block);
+		for (const v of tableVars) if (!variables.includes(v)) variables.push(v);
+	}
+	return variables;
+}
+/**
+* Extract template variables from a table
+*/
+function extractTableVariables(table) {
+	const variables = [];
+	for (const row of table.rows) for (const cell of row.cells) for (const cellContent of cell.content) if (cellContent.type === "paragraph") {
+		const vars = extractTemplateVariables(getParagraphText(cellContent));
+		for (const v of vars) if (!variables.includes(v)) variables.push(v);
+	} else {
+		const nestedVars = extractTableVariables(cellContent);
+		for (const v of nestedVars) if (!variables.includes(v)) variables.push(v);
+	}
+	return variables;
+}
+/**
+* Build sections from content based on section properties in paragraphs
+*
+* In OOXML, sections are delimited by:
+* 1. w:pPr/w:sectPr within a paragraph (marks end of a section)
+* 2. w:body/w:sectPr (final section properties)
+*
+* @param content - All block content
+* @param finalSectPr - Final section properties from body
+* @returns Array of sections
+*/
+function buildSections(content, finalSectPr) {
+	const sections = [];
+	let currentSectionContent = [];
+	for (const block of content) {
+		currentSectionContent.push(block);
+		if (block.type === "paragraph" && block.sectionProperties) {
+			sections.push({
+				properties: block.sectionProperties,
+				content: currentSectionContent
+			});
+			currentSectionContent = [];
+		}
+	}
+	if (currentSectionContent.length > 0 || sections.length === 0) sections.push({
+		properties: finalSectPr ?? getDefaultSectionProperties(),
+		content: currentSectionContent
+	});
+	return sections;
+}
+/**
+* Parse document.xml body content
+*
+* @param xml - Raw XML content of document.xml
+* @param styles - Parsed style map
+* @param theme - Parsed theme
+* @param numbering - Parsed numbering definitions
+* @param rels - Document relationships
+* @param media - Media files
+* @returns DocumentBody with content, sections, and template variables
+*/
+function parseDocumentBody(xml, styles = null, theme = null, numbering = null, rels = null, media = null) {
+	const result = { content: [] };
+	if (!xml) return result;
+	const documentEl = (parseXml(xml).elements ?? []).find((el) => el.type === "element" && (el.name === "w:document" || el.name?.endsWith(":document")));
+	if (!documentEl) return result;
+	const bodyEl = findChild(documentEl, "w", "body");
+	if (!bodyEl) return result;
+	result.content = parseBlockContent(bodyEl, styles, theme, numbering, rels, media, { rootXmlns: collectXmlnsDeclarations(documentEl) });
+	const finalSectPr = findChild(bodyEl, "w", "sectPr");
+	if (finalSectPr) result.finalSectionProperties = parseSectionProperties(finalSectPr);
+	result.sections = buildSections(result.content, result.finalSectionProperties);
+	return result;
+}
+/**
+* Get all paragraphs from document body (flattened)
+*/
+function getAllParagraphs(body) {
+	const paragraphs = [];
+	for (const block of body.content) if (block.type === "paragraph") paragraphs.push(block);
+	else if (block.type === "table") paragraphs.push(...getTableParagraphs(block));
+	return paragraphs;
+}
+/**
+* Get all paragraphs from a table (recursively)
+*/
+function getTableParagraphs(table) {
+	const paragraphs = [];
+	for (const row of table.rows) for (const cell of row.cells) for (const content of cell.content) if (content.type === "paragraph") paragraphs.push(content);
+	else paragraphs.push(...getTableParagraphs(content));
+	return paragraphs;
+}
+/**
+* Get all tables from document body
+*/
+function getAllTables(body) {
+	const tables = [];
+	for (const block of body.content) if (block.type === "table") {
+		tables.push(block);
+		tables.push(...getNestedTables(block));
+	}
+	return tables;
+}
+/**
+* Get nested tables from a table (recursively)
+*/
+function getNestedTables(table) {
+	const tables = [];
+	for (const row of table.rows) for (const cell of row.cells) for (const content of cell.content) if (content.type === "table") {
+		tables.push(content);
+		tables.push(...getNestedTables(content));
+	}
+	return tables;
+}
+/**
+* Get plain text from entire document body
+*/
+function getDocumentText(body) {
+	const lines = [];
+	for (const block of body.content) if (block.type === "paragraph") lines.push(getParagraphText(block));
+	else if (block.type === "table") lines.push(getTableText(block));
+	return lines.join("\n");
+}
+/**
+* Get plain text from a table
+*/
+function getTableText(table) {
+	const lines = [];
+	for (const row of table.rows) {
+		const rowTexts = [];
+		for (const cell of row.cells) {
+			const cellTexts = [];
+			for (const content of cell.content) if (content.type === "paragraph") cellTexts.push(getParagraphText(content));
+			else cellTexts.push(getTableText(content));
+			rowTexts.push(cellTexts.join("\n"));
+		}
+		lines.push(rowTexts.join("	"));
+	}
+	return lines.join("\n");
+}
+/**
+* Count total paragraphs in document
+*/
+function getParagraphCount(body) {
+	return getAllParagraphs(body).length;
+}
+/**
+* Count total words in document (approximate)
+*/
+function getWordCount(body) {
+	const words = getDocumentText(body).trim().split(/\s+/u);
+	return words.length > 0 && words[0] !== "" ? words.length : 0;
+}
+/**
+* Count total characters in document
+*/
+function getCharacterCount(body) {
+	return getDocumentText(body).length;
+}
+/**
+* Get section count
+*/
+function getSectionCount(body) {
+	return body.sections?.length ?? 1;
+}
+/**
+* Check if document has template variables
+*/
+function hasTemplateVariables(body) {
+	return extractAllTemplateVariables(body.content).length > 0;
+}
+//#endregion
+export { extractAllTemplateVariables, extractTemplateVariables, getAllParagraphs, getAllTables, getCharacterCount, getDocumentText, getParagraphCount, getSectionCount, getWordCount, hasTemplateVariables, parseDocumentBody };

package/dist/docx/drawingUtils.d.ts

@@ -0,0 +1,56 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+
+//#region src/docx/drawingUtils.d.ts
+/**
+ * Parse a color value from a DrawingML element.
+ * Handles: a:srgbClr, a:schemeClr, a:sysClr, a:prstClr
+ * Applies shade/tint modifiers when present.
+ */
+declare function parseColorElement(element: XmlElement | null): document_d_exports.ColorValue | undefined;
+/**
+ * Parse fill from shape properties (a:solidFill, a:noFill, a:gradFill).
+ */
+declare function parseFill(spPr: XmlElement | null): document_d_exports.ShapeFill | undefined;
+/**
+ * Parse outline from shape properties (a:ln).
+ */
+declare function parseOutline(spPr: XmlElement | null): document_d_exports.ShapeOutline | undefined;
+/**
+ * Parse horizontal position from wp:positionH element.
+ */
+declare function parsePositionH(posH: XmlElement | null): document_d_exports.ImagePosition["horizontal"] | undefined;
+/**
+ * Parse vertical position from wp:positionV element.
+ */
+declare function parsePositionV(posV: XmlElement | null): document_d_exports.ImagePosition["vertical"] | undefined;
+/**
+ * Parse position for anchored drawings (combines positionH + positionV).
+ */
+declare function parseAnchorPosition(anchor: XmlElement): document_d_exports.ImagePosition | undefined;
+/** Known wrap element names */
+declare const WRAP_ELEMENT_NAMES: string[];
+/**
+ * Parse wrap settings from a wrap element.
+ *
+ * Distance attributes (distT/distB/distL/distR) can appear on both
+ * the anchor element and the wrap child. Wrap child values take priority;
+ * anchor-level values are used as fallbacks.
+ */
+declare function parseWrapElement(wrapEl: XmlElement | null, behindDoc: boolean, anchorDistances?: {
+  distT?: number;
+  distB?: number;
+  distL?: number;
+  distR?: number;
+}): document_d_exports.ImageWrap;
+/**
+ * Parse wrap from an anchor element (finds wrap child internally).
+ */
+declare function parseAnchorWrap(anchor: XmlElement): document_d_exports.ImageWrap | undefined;
+/**
+ * Resolve a ColorValue to a CSS hex string using default theme colors.
+ * For use when no Theme object is available (e.g., shape/text box parsing).
+ */
+declare function resolveColorValueToHex(color: document_d_exports.ColorValue | undefined): string | undefined;
+//#endregion
+export { WRAP_ELEMENT_NAMES, parseAnchorPosition, parseAnchorWrap, parseColorElement, parseFill, parseOutline, parsePositionH, parsePositionV, parseWrapElement, resolveColorValueToHex };